TypeScript 首次準入與歷史信任

TypeScript AdmissionService 在六階段 Signed Document 驗證器 (MWP-ADM-005) 之上分層首次準入和歷史信任。與語言無關的流程見本地首次準入和歷史信任運行時頁面，確切要求見本地首次準入和歷史信任條款。

公共適配器和結果

公開 API	責任
`AdmissionCurrentKeyResolver.resolveCurrent`	同步返回完整的 Organization 範圍的 Registry 證據，表明部署斷言對於該決策是最新的。
`TrustedAdmissionContext.issue`	同步或非同步下發可信任記錄ID、受理即時、權威不在後才接受服務。
`AdmissionLog.lookup`	非同步返回`{ status: "found", record }`或`{ status: "authoritative-absence" }`。快取未命中、逾時、未經身份驗證的缺席和不確定狀態在 MWP-ADM-003 下關閉失敗。
`AdmissionLog.appendOrReturnExisting`	以原子方式追加候選位元組或透過經過驗證的服務身分返回並發權威獲勝者。
`AuthenticatedAdmissionRecord`	將 `recordBytes` 綁定到適配器驗證的服務，以便 MWP-ADM-009 可以驗證傳回的記錄。
`AdmissionService.prepareFirstAdmission`	從 SDK 產生的 `VerifiedSignedDocument` 建立並驗證候選證據。它並不附加或暗示承認。
`AdmissionService.admitFirst`	在 MWP-ADM-006 下執行當前驗證、權威查找、候選創建、原子附加或返回現有以及返回記錄驗證。
`AdmissionService.verifyHistoricalAdmission`	根據 MWP-ADM-008 的要求，使用歷史 Registry 證據重新運行六階段驗證，並需要現有記錄而不發布上下文或附加。
`AdmittedSignedDocument`	返回不可變的 `verified` 和 `record` 證據以及防禦性 `recordBytes` 副本。

確切的權威缺席值為 { status: "authoritative-absence" }。呼叫者提供的信任布林值不是準入查找結果，絕不能選擇成功路徑。

首次準入呼叫順序

admitFirst 在查閱日誌之前完成所有六個簽章文件階段。找到的記錄經過驗證並返回，無需發出可信上下文或附加。權威缺席後，服務發布可信任上下文，準備規範候選字節，呼叫 appendOrReturnExisting，並驗證實際傳回的記錄。只有當其架構、經過驗證的服務、文件綁定和可信任時間通過 MWP-ADM-009 和 MWP-ADM-010 時，並發獲勝者才是可接受的。

歷史回放

歷史重播使用保留的 Registry 歷史記錄重新運行驗證，需要 status: "found"，並且從不呼叫 TrustedAdmissionContext.issue 或 AdmissionLog.appendOrReturnExisting。匹配的記錄ID表明恢復了相同的權威記錄；它們不證明 Command 新鮮度、簽署者授權、狀態機接受或便攜式日誌證明驗證。這些在 MWP-ADM-013 和 MWP-ADM-014 下保持獨立。

誤差面

AdmissionError 公開 wireCode: "AUTH_INVALID_SIGNATURE" 並受保護的 auditDetail.stage: "admission"。穩定的受保護原因可區分缺失、衝突、畸形、未經驗證、不可用、不確定和自錨證據，同時保留 MWP-ADM-012 所需的非神諭線結果。

適配器可能會拋出 AdmissionLogError 以及受支援的準入原因。其他適配器例外不會自動重新分類。部署必須刻意映射其失敗，並且不得將一般成功、可用性或快取狀態視為經過驗證的證據。

可運行的精確固定範例

這個範例確定性地導出一個 Ed25519 key，建構一個完整的 Registry 快照並簽名 Command，並提供類型化記憶體適配器。固定種子是演示材料，絕不能在範例之外使用。

import {
  createPrivateKey,
  createPublicKey,
  sign as nodeSign,
  type KeyObject,
} from "node:crypto";

import {
  AdmissionService,
  SignedDocumentCodec,
  SignedDocumentKind,
  canonicalJsonBytes,
  encodeBase64Url,
  sha256Hex,
  type AdmissionContextValue,
  type AdmissionCurrentKeyResolver,
  type AdmissionLog,
  type AdmissionLookup,
  type AuthenticatedAdmissionRecord,
  type KeyRegistrySnapshot,
  type KeyResolutionRequest,
  type KeyResolver,
  type Principal,
  type SigningKey,
  type TrustedAdmissionContext,
} from "@missionweaveprotocol/sdk";

const AGENT_ID = "urn:missionweaveprotocol:agent:website-example";
const KEY_ID = "urn:missionweaveprotocol:key:website-example";
const ORGANIZATION_ID = "urn:missionweaveprotocol:organization:website-example";
const ADMISSION_SERVICE: Principal = Object.freeze({
  type: "service",
  id: "urn:missionweaveprotocol:service:admission",
});

class DeterministicSigningKey implements SigningKey {
  public readonly algorithm = "Ed25519" as const;
  public readonly keyId = KEY_ID;
  public readonly publicKeyBytes: Uint8Array;
  readonly #privateKey: KeyObject;

  public constructor() {
    // prettier-ignore
    const seed = Buffer.from(Array.from({ length: 32 }, (_, index) => index + 1));
    this.#privateKey = createPrivateKey({
      format: "der",
      key: Buffer.concat([
        Buffer.from("302e020100300506032b657004220420", "hex"),
        seed,
      ]),
      type: "pkcs8",
    });
    const spki = createPublicKey(this.#privateKey).export({
      format: "der",
      type: "spki",
    });
    this.publicKeyBytes = new Uint8Array(spki.subarray(-32));
  }

  public sign(bytes: Uint8Array): Uint8Array {
    return new Uint8Array(nodeSign(null, Buffer.from(bytes), this.#privateKey));
  }
}

class CurrentRegistryFixture
  implements AdmissionCurrentKeyResolver, KeyResolver
{
  readonly #snapshot: KeyRegistrySnapshot;

  public constructor(snapshot: KeyRegistrySnapshot) {
    this.#snapshot = snapshot;
  }

  public resolveCurrent(request: KeyResolutionRequest): KeyRegistrySnapshot {
    void request;
    return this.copySnapshot();
  }

  public resolve(request: KeyResolutionRequest): KeyRegistrySnapshot {
    void request;
    return this.copySnapshot();
  }

  private copySnapshot(): KeyRegistrySnapshot {
    return {
      completeness: "organization-wide",
      organizationId: this.#snapshot.organizationId,
      bindings: this.#snapshot.bindings.map((binding) => ({
        ...binding,
        principal: { ...binding.principal },
        validityHistory: binding.validityHistory.map((entry) => ({ ...entry })),
      })),
    };
  }
}

class FixedTrustedAdmissionContext implements TrustedAdmissionContext {
  public issue(
    organizationId: string,
    signingHash: string,
  ): AdmissionContextValue {
    const logicalKeyDigest = sha256Hex(`${organizationId}\0${signingHash}`);
    return {
      admissionRecordId: `urn:missionweaveprotocol:admission-record:${logicalKeyDigest}`,
      trustedAcceptedAt: "2026-07-15T00:05:00Z",
      acceptedBy: ADMISSION_SERVICE,
    };
  }
}

function copyRecord(
  record: AuthenticatedAdmissionRecord,
): AuthenticatedAdmissionRecord {
  return {
    recordBytes: Uint8Array.from(record.recordBytes),
    authenticatedService: { ...record.authenticatedService },
  };
}

class InMemoryAdmissionLog implements AdmissionLog {
  readonly #records = new Map<string, AuthenticatedAdmissionRecord>();
  public appendCount = 0;

  public async lookup(
    organizationId: string,
    signingHash: string,
  ): Promise<AdmissionLookup> {
    const record = this.#records.get(this.key(organizationId, signingHash));
    return record
      ? { status: "found", record: copyRecord(record) }
      : { status: "authoritative-absence" };
  }

  public async appendOrReturnExisting(
    organizationId: string,
    signingHash: string,
    candidateBytes: Uint8Array,
  ): Promise<AuthenticatedAdmissionRecord> {
    const key = this.key(organizationId, signingHash);
    const existing = this.#records.get(key);
    if (existing) return copyRecord(existing);

    const candidate = copyRecord({
      recordBytes: candidateBytes,
      authenticatedService: ADMISSION_SERVICE,
    });
    this.#records.set(key, candidate);
    this.appendCount += 1;
    return copyRecord(candidate);
  }

  private key(organizationId: string, signingHash: string): string {
    return `${organizationId}\0${signingHash}`;
  }
}

async function main(): Promise<void> {
  const signingKey: SigningKey & { readonly publicKeyBytes: Uint8Array } =
    new DeterministicSigningKey();
  const registry = new CurrentRegistryFixture({
    completeness: "organization-wide",
    organizationId: ORGANIZATION_ID,
    bindings: [
      {
        keyId: KEY_ID,
        principal: { type: "agent", id: AGENT_ID },
        algorithm: "Ed25519",
        publicKey: encodeBase64Url(signingKey.publicKeyBytes),
        validFrom: "2026-07-01T00:00:00Z",
        validityHistory: [],
      },
    ],
  });

  const signedDocument = new SignedDocumentCodec().sign(
    SignedDocumentKind.Command,
    {
      protocolVersion: "0.1",
      actionId: "urn:uuid:11111111-2222-4333-8444-555555555555",
      actor: { type: "agent", id: AGENT_ID },
      sessionEpoch: 1,
      membershipEpoch: 1,
      groupId: "urn:missionweaveprotocol:group:website-example",
      kind: "message.post",
      correlationId: "urn:uuid:aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
      issuedAt: "2026-07-15T00:00:00Z",
      payload: { text: "Admission example" },
    },
    signingKey,
  );
  const documentBytes = canonicalJsonBytes(signedDocument);
  const admissionLog = new InMemoryAdmissionLog();
  const service = new AdmissionService();

  const first = await service.admitFirst(
    SignedDocumentKind.Command,
    documentBytes,
    registry,
    admissionLog,
    new FixedTrustedAdmissionContext(),
  );
  const historical = await service.verifyHistoricalAdmission(
    SignedDocumentKind.Command,
    documentBytes,
    registry,
    admissionLog,
  );

  if (
    !(first.record.admissionRecordId === historical.record.admissionRecordId)
  ) {
    throw new Error("historical replay returned a different Admission record");
  }
  if (!(first.verified.signingHash === historical.verified.signingHash)) {
    throw new Error("historical replay returned a different signing hash");
  }
  if (!(Buffer.compare(first.recordBytes, historical.recordBytes) === 0)) {
    throw new Error("historical replay returned different record bytes");
  }
  if (!(admissionLog.appendCount === 1)) {
    throw new Error("Admission Log did not append exactly once");
  }

  console.log("first admission:", first.record.admissionRecordId);
  console.log("historical replay:", historical.record.admissionRecordId);
}

await main();

從一個精確的 SDK 結帳、類型檢查並運行如下：

npm ci
cp /absolute/path/to/examples/sdk/typescript/admission.ts examples/website-admission.ts
npm run typecheck:examples
npm run build
node --experimental-strip-types examples/website-admission.ts

該套件支援 Node.js 20。直接僅條帶執行此 .ts 來源需要 Node.js 22 或更高版本；在 Node.js 20 上，將其與專案一起轉譯 TypeScript 在運行發出的 ESM 之前的工具鏈。預期輸出包含相同的記錄 ID first admission 和 historical replay。該程式還斷言匹配的簽章雜湊值和記錄位元組以及精確的一個附加。