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 密钥，构造完整的 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 上，在运行发出的 ESM 之前使用项目 TypeScript 工具链对其进行转译。预期输出包含 first admission 和 historical replay 的相同记录 ID。该程序还断言匹配的签名哈希值和记录字节以及精确的一个附加。