TypeScript Première admission et confiance historique

TypeScript Première admission et confiance historique

Le TypeScript AdmissionService superpose la première admission et la confiance historique au-dessus du vérificateur Signed Document en six étapes (MWP-ADM-005). Le flux indépendant de la langue est la page d’exécution locale de première admission et de confiance historique, et les exigences exactes sont les clauses locales de première admission et de confiance historique.

## Adaptateurs et résultats publics

Public API	Responsabilité
AdmissionCurrentKeyResolver.resolveCurrent	Renvoie de manière synchrone la preuve complète Organization Registry que le déploiement affirme être à jour pour cette décision.
TrustedAdmissionContext.issue	Émettez de manière synchrone ou asynchrone l’ID d’enregistrement de confiance, l’acceptation instantanée et l’acceptation du service uniquement après une absence faisant autorité.
AdmissionLog.lookup	Renvoie de manière asynchrone { status: "found", record } ou { status: "authoritative-absence" }. Échec de l’échec du cache, du délai d’attente, de l’absence non authentifiée et de l’état indéterminé sous MWP-ADM-003.
AdmissionLog.appendOrReturnExisting	Ajoutez atomiquement des octets candidats ou renvoyez le gagnant faisant autorité simultané via une identité de service authentifiée.
AuthenticatedAdmissionRecord	Liez recordBytes au service authentifié par l’adaptateur afin que MWP-ADM-009 puisse valider l’enregistrement renvoyé.
AdmissionService.prepareFirstAdmission	Créez et validez des preuves de candidat à partir d’un SDK produit par VerifiedSignedDocument. Cela n’ajoute ni n’implique une admission.
AdmissionService.admitFirst	Effectuez la vérification actuelle, la recherche faisant autorité, la création de candidats, l’ajout ou le retour atomique de l’existant et la validation des enregistrements renvoyés sous MWP-ADM-006.
AdmissionService.verifyHistoricalAdmission	Réexécutez la vérification en six étapes avec les preuves historiques Registry et exigez un enregistrement existant sans émettre de contexte ni ajouter d’ajout, comme l’exige MWP-ADM-008.
AdmittedSignedDocument	Renvoie les preuves immuables verified et record ainsi qu’une copie défensive recordBytes.

La valeur exacte d’absence faisant autorité est { status: "authoritative-absence" }. Un booléen de confiance fourni par l’appelant n’est pas un résultat de recherche d’admission et ne doit jamais sélectionner le chemin de réussite.

Ordre d’appel de première admission

Informative example

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

admitFirst termine les six étapes du document signé avant de consulter le journal. Un enregistrement trouvé est validé et renvoyé sans émettre de contexte fiable ni ajout. Après une absence faisant autorité, le service émet un contexte de confiance, prépare les octets candidats canoniques, appelle appendOrReturnExisting et valide l’enregistrement effectivement renvoyé. Un gagnant simultané n’est acceptable que lorsque son schéma, son service authentifié, sa liaison de document et son délai de confiance sont passés MWP-ADM-009 et MWP-ADM-010.

Relecture historique

Informative example

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

La relecture historique réexécute la vérification avec l’historique Registry conservé, nécessite status: "found" et n’appelle jamais TrustedAdmissionContext.issue ou AdmissionLog.appendOrReturnExisting. Les ID d’enregistrement correspondant démontrent la récupération du même enregistrement faisant autorité ; ils ne prouvent pas la fraîcheur Command, l’autorisation du signataire, l’acceptation de la machine d’état ou la vérification portable de la preuve de journal. Ceux-ci restent distincts sous MWP-ADM-013 et MWP-ADM-014.

Surface d’erreur

AdmissionError expose wireCode: "AUTH_INVALID_SIGNATURE" et auditDetail.stage: "admission" protégé. Les raisons protégées stables distinguent les preuves manquantes, contradictoires, mal formées, non authentifiées, indisponibles, indéterminées et auto-ancrées tout en préservant le résultat de fil non oraculaire requis par MWP-ADM-012.

Les adaptateurs peuvent lancer AdmissionLogError avec un motif d’admission pris en charge. Les autres exceptions d’adaptateur ne sont pas automatiquement recatégorisées. Les déploiements doivent cartographier délibérément leurs échecs et ne doivent pas traiter le succès générique, la disponibilité ou l’état du cache comme une preuve authentifiée.

Exemple d’exécution exacte épinglée

Informative example

L’exemple dérive de manière déterministe une clé Ed25519, construit un instantané Registry complet et Command signé, et fournit des adaptateurs en mémoire saisis. La graine fixée est du matériel de démonstration et ne doit jamais être utilisée en dehors de l’exemple.

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

À partir d’une extraction exacte SDK, tapez check et exécutez-la comme suit :

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

Le package prend en charge Node.js 20. L’exécution directe uniquement de cette source .ts nécessite Node.js 22 ou une version ultérieure ; sur Node.js 20, transpilez-le avec la chaîne d’outils du projet TypeScript avant d’exécuter l’ESM émis. La sortie attendue contient le même ID d’enregistrement pour first admission et historical replay. Le programme affirme également des hachages de signature et des octets d’enregistrement correspondants, ainsi qu’un seul ajout.

Implementation note

Remplacez CurrentRegistryFixture par des adaptateurs Registry actuels et historiques authentifiés, InMemoryAdmissionLog par un journal durable authentifié dont l’opération d’ajout ou de retour existante est atomique et FixedTrustedAdmissionContext par Organization contrôlé. temps de confiance et émission de service d’acceptation.

Remplacez DeterministicSigningKey par un service de clés appartenant au déploiement. Conservez les copies d’octets défensives et ne réduisez pas les limites d’autorité en un seul booléen de confiance fourni par l’appelant.