TypeScript First Admission and Historical Trust

TypeScript First Admission and Historical Trust

The TypeScript AdmissionService layers First Admission and Historical Trust above the six-stage Signed Document verifier (MWP-ADM-005). The language-independent flow is the local First Admission and Historical Trust runtime page, and the exact requirements are the local First-Admission and Historical-Trust clauses.

Public adapters and results

Public API	Responsibility
AdmissionCurrentKeyResolver.resolveCurrent	Synchronously return complete Organization-wide Registry evidence that the deployment asserts is current for this decision.
TrustedAdmissionContext.issue	Synchronously or asynchronously issue the trusted record ID, acceptance instant, and accepting service only after authoritative absence.
AdmissionLog.lookup	Asynchronously return { status: "found", record } or { status: "authoritative-absence" }. Cache miss, timeout, unauthenticated absence, and indeterminate state fail closed under MWP-ADM-003.
AdmissionLog.appendOrReturnExisting	Atomically append candidate bytes or return the concurrent authoritative winner through an authenticated service identity.
AuthenticatedAdmissionRecord	Bind recordBytes to the service authenticated by the adapter so MWP-ADM-009 can validate the returned record.
AdmissionService.prepareFirstAdmission	Create and validate candidate evidence from an SDK-produced VerifiedSignedDocument. It does not append or imply admission.
AdmissionService.admitFirst	Perform current verification, authoritative lookup, candidate creation, atomic append-or-return-existing, and returned-record validation under MWP-ADM-006.
AdmissionService.verifyHistoricalAdmission	Rerun six-stage verification with historical Registry evidence and require an existing record without issuing context or appending, as required by MWP-ADM-008.
AdmittedSignedDocument	Return immutable verified and record evidence plus a defensive recordBytes copy.

The exact authoritative absence value is { status: "authoritative-absence" }. A caller-provided trust boolean is not an Admission lookup outcome and must never select the success path.

First-admission call order

Informative example

const first = await new AdmissionService().admitFirst(
  SignedDocumentKind.Command,
  documentBytes,
  currentRegistry,
  admissionLog,
  trustedContext,
);

admitFirst completes all six signed-document stages before consulting the log. A found record is validated and returned without issuing trusted context or appending. After authoritative absence, the service issues trusted context, prepares canonical candidate bytes, calls appendOrReturnExisting, and validates the record actually returned. A concurrent winner is acceptable only when its Schema, authenticated service, document binding, and trusted time pass MWP-ADM-009 and MWP-ADM-010.

Historical replay

Informative example

const historical = await new AdmissionService().verifyHistoricalAdmission(
  SignedDocumentKind.Command,
  documentBytes,
  historicalRegistry,
  admissionLog,
);

Historical replay reruns verification with retained Registry history, requires status: "found", and never calls TrustedAdmissionContext.issue or AdmissionLog.appendOrReturnExisting. Matching record IDs demonstrate recovery of the same authoritative record; they do not prove Command freshness, signer authorization, state-machine acceptance, or portable log-proof verification. Those remain separate under MWP-ADM-013 and MWP-ADM-014.

Error surface

AdmissionError exposes wireCode: "AUTH_INVALID_SIGNATURE" and protected auditDetail.stage: "admission". Stable protected reasons distinguish missing, conflicting, malformed, unauthenticated, unavailable, indeterminate, and self-anchoring evidence while preserving the non-oracular wire result required by MWP-ADM-012.

Adapters may throw AdmissionLogError with a supported Admission reason. Other adapter exceptions are not automatically recategorized. Deployments must map their failures deliberately and must not treat generic success, availability, or cache state as authenticated evidence.

Runnable exact-pinned example

Informative example

The example deterministically derives one Ed25519 key, constructs a complete Registry snapshot and signed Command, and supplies typed in-memory adapters. The fixed seed is demonstration material and must never be used outside the example.

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();

From an exact SDK checkout, type-check and run it as follows:

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

The package supports Node.js 20. Direct strip-only execution of this .ts source requires Node.js 22 or newer; on Node.js 20, transpile it with the project TypeScript toolchain before running the emitted ESM. Expected output contains the same record ID for first admission and historical replay. The program also asserts matching signing hashes and record bytes and exactly one append.

Implementation note

Replace CurrentRegistryFixture with authenticated current and historical Registry adapters, InMemoryAdmissionLog with an authenticated durable log whose append-or-return-existing operation is atomic, and FixedTrustedAdmissionContext with Organization-controlled trusted time and accepting-service issuance.

Replace DeterministicSigningKey with a deployment-owned key service. Preserve defensive byte copies and do not collapse authority boundaries into one caller-provided trust boolean.