TypeScript Primera admisión y confianza histórica

TypeScript Primera admisión y confianza histórica

El TypeScript AdmissionService coloca la primera admisión y la confianza histórica por encima del verificador de seis etapas Signed Document (MWP-ADM-005). El flujo independiente del idioma es la página de tiempo de ejecución de confianza histórica y de primera admisión local , y los requisitos exactos son las cláusulas de confianza histórica y de primera admisión locales.

Adaptadores públicos y resultados.

Público API	Responsabilidad
AdmissionCurrentKeyResolver.resolveCurrent	Devuelve sincrónicamente evidencia Organization completa de Registry que la implementación afirma que está vigente para esta decisión.
TrustedAdmissionContext.issue	Emitir de forma síncrona o asíncrona la identificación del registro confiable, el instante de aceptación y el servicio de aceptación solo después de una constatación autoritativa de ausencia.
AdmissionLog.lookup	Devuelve asincrónicamente { status: "found", record } o { status: "authoritative-absence" }. Error de caché, tiempo de espera, ausencia no autenticada y error de estado indeterminado cerrado bajo MWP-ADM-003.
AdmissionLog.appendOrReturnExisting	Agregue atómicamente bytes candidatos o devuelva el registro autoritativo ganador de una carrera concurrente a través de una identidad de servicio autenticada.
AuthenticatedAdmissionRecord	Vincule recordBytes al servicio autenticado por el adaptador para que MWP-ADM-009 pueda validar el registro devuelto.
AdmissionService.prepareFirstAdmission	Cree y valide pruebas candidatas a partir de un VerifiedSignedDocument producido por SDK. No anexa ni implica admisión.
AdmissionService.admitFirst	Realice la verificación actual, la búsqueda autoritativa, la creación de candidatos, la validación atómica de anexar o devolver existente y de registros devueltos en MWP-ADM-006.
AdmissionService.verifyHistoricalAdmission	Vuelva a ejecutar la verificación de seis etapas con evidencia histórica autoritativa del Registry y exija un registro existente sin emitir contexto ni añadirlo, como requiere MWP-ADM-008.
AdmittedSignedDocument	Devuelve pruebas verified y record inmutables más una copia defensiva recordBytes.

El valor de ausencia autorizado exacto es { status: "authoritative-absence" }. Un valor booleano de confianza proporcionado por la persona que llama no es un resultado de búsqueda de admisión y nunca debe seleccionar la ruta exitosa.

Orden de llamada de primera admisión

Informative example

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

admitFirst completa las seis etapas del documento firmado antes de consultar el registro. Un registro encontrado se valida y se devuelve sin emitir un contexto confiable ni agregarlo. Después de una constatación autoritativa de ausencia, el servicio emite un contexto confiable, prepara bytes candidatos canónicos, llama a appendOrReturnExisting y valida el registro realmente devuelto. Un ganador simultáneo es aceptable solo cuando su esquema, servicio autenticado, enlace de documentos y tiempo de confianza pasan MWP-ADM-009 y MWP-ADM-010.

Repetición histórica

Informative example

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

La repetición histórica vuelve a ejecutar la verificación con el historial Registry retenido, requiere status: "found" y nunca llama a TrustedAdmissionContext.issue o AdmissionLog.appendOrReturnExisting. Los ID de registros coincidentes demuestran la recuperación del mismo registro autorizado; no prueban la frescura de Command, la autorización del firmante, la aceptación de la máquina de estados ni la verificación portátil a prueba de registros. Estos permanecen separados bajo MWP-ADM-013 y MWP-ADM-014.

Superficie de error

AdmissionError expone wireCode: "AUTH_INVALID_SIGNATURE" y protege auditDetail.stage: "admission". Los motivos protegidos estables distinguen las pruebas faltantes, conflictivas, mal formadas, no autenticadas, no disponibles, indeterminadas y autoancladas, al tiempo que preservan el resultado del cable no oracular requerido por MWP-ADM-012.

Los adaptadores pueden generar AdmissionLogError con un motivo de admisión admitido. Otras excepciones de adaptadores no se recategorizan automáticamente. Las implementaciones deben mapear sus fallas deliberadamente y no deben tratar el éxito genérico, la disponibilidad o el estado de la caché como evidencia autenticada.

Ejemplo ejecutable con fijación exacta

Informative example

El ejemplo deriva de manera determinista una clave Ed25519, construye una instantánea Registry completa y Command firmada, y proporciona adaptadores en memoria escritos. La semilla fija es material de demostración y nunca debe usarse fuera del ejemplo.

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

Desde un pago exacto SDK, escriba la verificación y ejecútelo de la siguiente manera:

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

El paquete es compatible con Node.js 20. La ejecución directa de solo tira de esta fuente .ts requiere Node.js 22 o posterior; en Node.js 20, transpílelo con la cadena de herramientas del proyecto TypeScript antes de ejecutar el ESM emitido. El resultado esperado contiene el mismo ID de registro para first admission y historical replay. El programa también afirma que los hashes de firma y los bytes de registro coinciden y exactamente un anexo.

Implementation note

Reemplace CurrentRegistryFixture con adaptadores Registry actuales e históricos autenticados, InMemoryAdmissionLog con un registro duradero autenticado cuya operación de agregar o devolver existente es atómica y FixedTrustedAdmissionContext con Tiempo de confianza controlado por Organization y emisión de servicio de aceptación.

Reemplace DeterministicSigningKey con un servicio de claves propiedad de la implementación. Conserve copias de bytes defensivas y no colapse los límites de autoridad en un valor booleano de confianza proporcionado por la persona que llama.