TypeScript Erstzulassung und historischer Trust

TypeScript Erstzulassung und historischer Trust

Der TypeScript AdmissionService legt Erstzulassung und historisches Vertrauen über dem sechsstufigen Verifizierer Signed Document (MWP-ADM-005)“. Der sprachunabhängige Ablauf ist die lokale Laufzeitseite für Erstzulassung und historisches Vertrauen, und die genauen Anforderungen sind die lokalen First-Admission- und Historical-Trust-Klauseln.

Öffentliche Adapter und Ergebnisse

Öffentlich API	Verantwortung
AdmissionCurrentKeyResolver.resolveCurrent	Geben Sie synchron den vollständigen Organization-weiten Registry-Beweis zurück, dass die Bereitstellung für diese Entscheidung aktuell ist.
TrustedAdmissionContext.issue	Geben Sie synchron oder asynchron die vertrauenswürdige Datensatz-ID, den Akzeptanzzeitpunkt und den Akzeptanzdienst erst nach maßgeblicher Abwesenheit aus.
AdmissionLog.lookup	Geben Sie { status: "found", record } oder { status: "authoritative-absence" } asynchron zurück. Cache-Fehler, Zeitüberschreitung, nicht authentifizierte Abwesenheit und unbestimmter Statusfehler geschlossen unter MWP-ADM-003.
AdmissionLog.appendOrReturnExisting	Hängen Sie Kandidatenbytes atomar an oder geben Sie den gleichzeitigen maßgeblichen Gewinner über eine authentifizierte Dienstidentität zurück.
AuthenticatedAdmissionRecord	Binden Sie recordBytes an den vom Adapter authentifizierten Dienst, damit MWP-ADM-009 den zurückgegebenen Datensatz validieren kann.
AdmissionService.prepareFirstAdmission	Erstellen und validieren Sie Kandidatennachweise aus einem von SDK erstellten VerifiedSignedDocument. Es stellt keine Zulassung dar und impliziert auch keine Zulassung.
AdmissionService.admitFirst	Führen Sie unter MWP-ADM-006 eine aktuelle Überprüfung, eine maßgebliche Suche, eine Kandidatenerstellung, eine atomare Append-or-Return-Existing-Funktion und eine Validierung zurückgegebener Datensätze durch.
AdmissionService.verifyHistoricalAdmission	Führen Sie die sechsstufige Überprüfung erneut mit historischen Registry-Beweisen durch und fordern Sie einen vorhandenen Datensatz an, ohne Kontext auszugeben oder anzuhängen, wie in MWP-ADM-008 erforderlich.
AdmittedSignedDocument	Geben Sie unveränderliche verified- und record-Beweise sowie eine defensive recordBytes-Kopie zurück.

Der genaue maßgebliche Abwesenheitswert ist { status: "authoritative-absence" }. Ein vom Anrufer bereitgestellter boolescher Vertrauensstellungswert ist kein Ergebnis der Zulassungssuche und darf niemals den Erfolgspfad auswählen.

Reihenfolge der Erstzulassung

Informative example

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

admitFirst schließt alle sechs Phasen des signierten Dokuments ab, bevor das Protokoll konsultiert wird. Ein gefundener Datensatz wird validiert und zurückgegeben, ohne dass ein vertrauenswürdiger Kontext ausgegeben oder ein Anhang hinzugefügt wird. Nach autoritativer Abwesenheit gibt der Dienst vertrauenswürdigen Kontext aus, bereitet kanonische Kandidatenbytes vor, ruft appendOrReturnExisting auf und validiert den tatsächlich zurückgegebenen Datensatz. Ein gleichzeitiger Gewinner ist nur akzeptabel, wenn sein Schema, sein authentifizierter Dienst, seine Dokumentbindung und seine vertrauenswürdige Zeit MWP-ADM-009 und MWP-ADM-010.

Historische Wiederholung

Informative example

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

Die Überprüfung der historischen Wiederholung erfolgt mit beibehaltener Wiederholung Registry Geschichte, erfordert status: "found", und ruft nie an TrustedAdmissionContext.issue oder AdmissionLog.appendOrReturnExisting. Übereinstimmende Datensatz-IDs zeigen die Wiederherstellung desselben maßgeblichen Datensatzes. sie beweisen es nicht Command Aktualität, Unterzeichnerautorisierung, Zustandsmaschinenakzeptanz oder tragbare protokollsichere Überprüfung. Diese bleiben gemäß MWP-ADM-013 und MWP-ADM-014 getrennt.

Fehleroberfläche

AdmissionError entlarvt wireCode: "AUTH_INVALID_SIGNATURE" und geschützt auditDetail.stage: "admission". Stabile geschützte Gründe unterscheiden fehlende, widersprüchliche, fehlerhafte, nicht authentifizierte, nicht verfügbare, unbestimmte und selbstverankernde Beweise und bewahren gleichzeitig das von MWP-ADM-012 geforderte nicht-orakelhafte Drahtergebnis.

Adapter können werfen AdmissionLogError mit einem unterstützten Zulassungsgrund. Andere Adapterausnahmen werden nicht automatisch neu kategorisiert. Bereitstellungen müssen ihre Fehler bewusst abbilden und dürfen allgemeinen Erfolg, Verfügbarkeit oder Cache-Status nicht als authentifizierten Beweis behandeln.

Ausführbares, exakt angeheftetes Beispiel

Informative example

Das Beispiel leitet deterministisch einen Ed25519-Schlüssel ab, erstellt einen vollständigen Registry-Snapshot und signierten Command und stellt typisierte In-Memory-Adapter bereit. Der feste Seed ist Demonstrationsmaterial und darf niemals außerhalb des Beispiels verwendet werden.

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

Führen Sie bei einem exakten SDK-Checkout eine Typprüfung durch und führen Sie ihn wie folgt aus:

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

Das Paket unterstützt Node.js 20. Die direkte Strip-Only-Ausführung dieser .ts-Quelle erfordert Node.js 22 oder neuer; Transpilieren Sie es auf Node.js 20 mit der Toolchain des Projekts TypeScript, bevor Sie das ausgegebene ESM ausführen. Die erwartete Ausgabe enthält dieselbe Datensatz-ID für first admission und historical replay. Das Programm stellt außerdem passende Signatur-Hashes und Datensatzbytes sowie genau ein Anhängen sicher.

Implementation note

Ersetzen Sie CurrentRegistryFixture durch authentifizierte aktuelle und historische Registry-Adapter, InMemoryAdmissionLog durch ein authentifiziertes dauerhaftes Protokoll, dessen Append-or-Return-Existing-Vorgang atomar ist, und FixedTrustedAdmissionContext durch Organization-gesteuerte vertrauenswürdige Zeit und Annahmedienstausgabe.

Ersetzen Sie DeterministicSigningKey durch einen Schlüsseldienst im Besitz der Bereitstellung. Behalten Sie defensive Bytekopien bei und reduzieren Sie Autoritätsgrenzen nicht auf einen vom Aufrufer bereitgestellten booleschen Vertrauenswert.