@ai-wayfinding/core 0.1.1

package/README.md

@@ -0,0 +1,24 @@
+# Wayfinding protocol core
+
+`@ai-wayfinding/core` supplies the portable types and pure protocol operations for encrypted team spaces. An **enclave** is the technical name in code for that space; a **journey** is what people call it. This package has no server, network client, or storage adapter. It uses Web Crypto and age encryption in Node 22+, browsers, and Cloudflare Workers.
+
+## Using the package
+
+Install dependencies at the repository root with `npm ci`. Run `npm run typecheck -w packages/core`, `npm run build -w packages/core`, and `npm test -w packages/core`. Run the same tests in workerd with `npm run test:workers -w packages/core` and in Chromium with `npm run test:browser -w packages/core`. If your Chromium installation differs from Playwright's, set `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` to its executable.
+
+The top-level module exports `newId`, `createAgeIdentity`, `createAgentIdentity`, `createSigningIdentity`, `sealIdentity`, `openIdentity`, `generateJourneyKey`, `wrapJourneyKey`, `rotateJourneyKey`, `seal`, `open`, `parseRecord`, `serializeRecord`, `signEntry`, `verifyLog`, `removeAndRotate`, `exportJourney`, and `importJourney`. Age recipients and identities may also be custom implementations, including browser-only passkey recipients. An agent's X25519 private `CryptoKey` is non-extractable; a person's age identity and Ed25519 private key are strings that can be sealed to recipients for storage. Store neither unsealed private material nor a usable journey key on a server.
+
+## Formats
+
+An envelope has `{ outside, nonce, ciphertext }`. Only `outside` is plain: `{ v:1, id, journey, seq?, epoch, size, createdAt }`. `size` is the UTF-8 byte length of the encrypted JSON before encryption. `nonce` and `ciphertext` are base64. The decrypted JSON carries `{ type, typeVersion, body }`, with additional fields preserved. The twelve-byte AES-GCM nonce is fresh on each seal. Authenticated associated data covers **every** outside field, including `seq` when present; therefore, if the server assigns a sequence, it must reserve the sequence **before** the client seals the record. Changing it afterwards fails decryption. See [the public protocol](../../docs/journey-protocol.md) for item, comment, deletion, and membership details.
+
+A signed membership entry is `{ v:1, seq, prev, at, actor, type, body, sig }`. For signatures, remove `sig`, sort object keys by JavaScript string ordering recursively, keep array order, render compact JSON, encode UTF-8 and sign with Ed25519. The signature is base64. `prev` is the base64 SHA-256 hash of the complete preceding entry in the same canonical encoding, or `null` at genesis. `verifyLog` returns either a derived state or a typed error with a failing sequence number. Unknown membership types return `client-too-old`. Genesis may include an optional signed `description` (up to 2,000 characters) and `journeyKind` (`individual` or `team`); both stay in the encrypted membership log, not the plain registry. The export file is an age-encrypted JSON archive of the log, envelopes, and epoch key wraps; imports verify the log and open each encrypted envelope with an available identity.
+
+## Threat model
+
+- The server can see journey identifiers, sizes, sequence numbers, key epochs, timestamps, and a plain journey name. Membership entries must be encrypted by the client before server storage; storing the in-memory log format plainly would reveal member identifiers and grants. The server cannot decrypt an envelope without a member's key.
+- The server can deny service, delay writes, omit records, replay an old complete log, or refuse a key rotation. Clients need an independently retained log checkpoint to detect rollback; this package does not provide one.
+- The server cannot forge a verified membership change or a new `members.manage` holder without a current person's Ed25519 signing key. A client must call `verifyLog` before wrapping a key for anyone.
+- A removed member cannot unwrap the new key epoch. They can keep everything they downloaded and any old key they already know.
+- The server cannot alter an authenticated outside field or ciphertext without `open` failing. A client must still check the server's access policy and sequence allocation separately.
+- A compromised member device or exported recovery identity can read whatever epochs that identity can unwrap. This package does not implement passkeys, account recovery, or secure device storage.

package/dist/codec.d.ts

@@ -0,0 +1,5 @@
+export declare const encode: (bytes: Uint8Array) => string;
+export declare const decode: (text: string) => Uint8Array;
+export declare const asBuffer: (bytes: Uint8Array) => ArrayBuffer;
+export declare const utf8: (text: string) => Uint8Array;
+export declare const text: (bytes: Uint8Array) => string;

package/dist/codec.js

@@ -0,0 +1,5 @@
+export const encode = (bytes) => btoa(Array.from(bytes, b => String.fromCharCode(b)).join(''));
+export const decode = (text) => Uint8Array.from(atob(text), c => c.charCodeAt(0));
+export const asBuffer = (bytes) => Uint8Array.from(bytes).buffer;
+export const utf8 = (text) => new TextEncoder().encode(text);
+export const text = (bytes) => new TextDecoder('utf-8', { fatal: true }).decode(bytes);

package/dist/envelope.d.ts

@@ -0,0 +1,18 @@
+import type { JourneyKey } from './teamKey.js';
+import type { ProtocolRecord } from './types.js';
+export interface OuterMeta {
+    v: 1;
+    id: string;
+    journey: string;
+    seq?: number;
+    epoch: number;
+    size: number;
+    createdAt: string;
+}
+export interface Envelope {
+    outside: OuterMeta;
+    nonce: string;
+    ciphertext: string;
+}
+export declare function seal(inner: ProtocolRecord, outerMeta: Omit<OuterMeta, 'v' | 'size'>, journeyKey: JourneyKey): Promise<Envelope>;
+export declare function open(envelope: Envelope, journeyKey: JourneyKey): Promise<ProtocolRecord>;

package/dist/envelope.js

@@ -0,0 +1,34 @@
+import { asBuffer, decode, encode, text, utf8 } from './codec.js';
+const fields = ['createdAt', 'epoch', 'id', 'journey', 'seq', 'size', 'v'];
+function aad(outside) {
+    if (Object.keys(outside).some(k => !fields.includes(k)))
+        throw new Error('Unexpected outside field');
+    return utf8(JSON.stringify(fields.map(k => [k, Object.hasOwn(outside, k) ? outside[k] : null])));
+}
+function checkKey(key, epoch) {
+    if (key.epoch !== epoch || key.key.length !== 32)
+        throw new Error('Wrong journey key epoch');
+}
+export async function seal(inner, outerMeta, journeyKey) {
+    checkKey(journeyKey, outerMeta.epoch);
+    const plaintext = utf8(JSON.stringify(inner));
+    const outside = { v: 1, id: outerMeta.id, journey: outerMeta.journey, ...(outerMeta.seq === undefined ? {} : { seq: outerMeta.seq }), epoch: outerMeta.epoch, size: plaintext.length, createdAt: outerMeta.createdAt };
+    const nonce = crypto.getRandomValues(new Uint8Array(12));
+    const key = await crypto.subtle.importKey('raw', asBuffer(journeyKey.key), 'AES-GCM', false, ['encrypt']);
+    const ciphertext = await crypto.subtle.encrypt({ name: 'AES-GCM', iv: asBuffer(nonce), additionalData: asBuffer(aad(outside)) }, key, asBuffer(plaintext));
+    return { outside, nonce: encode(nonce), ciphertext: encode(new Uint8Array(ciphertext)) };
+}
+export async function open(envelope, journeyKey) {
+    checkKey(journeyKey, envelope.outside.epoch);
+    const nonce = decode(envelope.nonce);
+    if (nonce.length !== 12)
+        throw new Error('Invalid nonce');
+    const key = await crypto.subtle.importKey('raw', asBuffer(journeyKey.key), 'AES-GCM', false, ['decrypt']);
+    const plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: asBuffer(nonce), additionalData: asBuffer(aad(envelope.outside)) }, key, asBuffer(decode(envelope.ciphertext))));
+    if (plaintext.length !== envelope.outside.size)
+        throw new Error('Invalid size');
+    const record = JSON.parse(text(plaintext));
+    if (!record || typeof record !== 'object' || Array.isArray(record) || typeof record.type !== 'string' || !Number.isSafeInteger(record.typeVersion) || !(record.body && typeof record.body === 'object' && !Array.isArray(record.body)))
+        throw new Error('Invalid record');
+    return record;
+}

package/dist/ids.d.ts

@@ -0,0 +1,2 @@
+export declare function newId(): string;
+export declare function isId(value: unknown): value is string;

package/dist/ids.js

@@ -0,0 +1,25 @@
+const alphabet = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+let lastTime = -1;
+let lastRandom = 0n;
+const maxRandom = (1n << 80n) - 1n;
+function base32(value, length) {
+    let result = '';
+    for (let i = 0; i < length; i++) {
+        result = alphabet[Number(value & 31n)] + result;
+        value >>= 5n;
+    }
+    return result;
+}
+export function newId() {
+    const now = Date.now();
+    if (now > lastTime || lastRandom === maxRandom) {
+        lastTime = Math.max(now, lastTime + (lastRandom === maxRandom ? 1 : 0));
+        lastRandom = crypto.getRandomValues(new BigUint64Array(2)).reduce((v, part) => (v << 64n) | part, 0n) & maxRandom;
+    }
+    else
+        lastRandom++;
+    return base32(BigInt(lastTime), 10) + base32(lastRandom, 16);
+}
+export function isId(value) {
+    return typeof value === 'string' && /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/.test(value);
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './types.js';
+export * from './ids.js';
+export * from './keys.js';
+export * from './teamKey.js';
+export * from './envelope.js';
+export * from './items.js';
+export * from './log.js';
+export * from './removal.js';
+export * from './transfer.js';
+export * from './versions.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from './types.js';
+export * from './ids.js';
+export * from './keys.js';
+export * from './teamKey.js';
+export * from './envelope.js';
+export * from './items.js';
+export * from './log.js';
+export * from './removal.js';
+export * from './transfer.js';
+export * from './versions.js';

package/dist/items.d.ts

@@ -0,0 +1,52 @@
+import type { JsonObject, ProtocolRecord, Validation } from './types.js';
+export interface ItemBody extends JsonObject {
+    id: string;
+    itemType: string;
+    title: string;
+    body: string;
+    author: string;
+    authoredBy: 'human' | 'agent' | 'mixed';
+    created: string;
+    tags: string[];
+    links?: {
+        to: string;
+        rel: string;
+    }[];
+    replaces?: string;
+    sharedFrom?: string;
+    resourceKind?: string;
+}
+export interface CommentBody extends JsonObject {
+    id: string;
+    item: string;
+    onVersion: string;
+    author: string;
+    authoredBy: 'human' | 'agent' | 'mixed';
+    at: string;
+    inReplyTo?: string;
+    body: string;
+}
+export interface DeleteBody extends JsonObject {
+    target: string;
+}
+export interface RecordDefinition {
+    name: string;
+    version: number;
+    validate(body: JsonObject): Validation;
+    upgrade?: (previous: JsonObject) => JsonObject;
+}
+export interface KnownRecord {
+    kind: 'known';
+    record: ProtocolRecord;
+}
+export interface UnknownRecord {
+    kind: 'unknown';
+    raw: ProtocolRecord;
+}
+export type ParsedRecord = KnownRecord | UnknownRecord;
+export declare function validateItem(body: JsonObject): Validation;
+export declare function validateComment(body: JsonObject): Validation;
+export declare function validateDelete(body: JsonObject): Validation;
+export declare const itemDefinitions: readonly RecordDefinition[];
+export declare function parseRecord(record: ProtocolRecord, definitions?: readonly RecordDefinition[]): ParsedRecord;
+export declare function serializeRecord(parsed: ParsedRecord): ProtocolRecord;

package/dist/items.js

@@ -0,0 +1,45 @@
+import { isId } from './ids.js';
+const valid = () => ({ ok: true });
+const invalid = (reason) => ({ ok: false, reason });
+const string = (value) => typeof value === 'string';
+const authored = (value) => value === 'human' || value === 'agent' || value === 'mixed';
+const optional = (value, check) => value === undefined || check(value);
+export function validateItem(body) {
+    if (!isId(body.id) || !string(body.itemType) || !body.itemType || !string(body.title) || !string(body.body) || !string(body.author) || !authored(body.authoredBy) || !string(body.created) || !Array.isArray(body.tags) || !body.tags.every(string))
+        return invalid('Invalid item fields');
+    if (!optional(body.links, v => Array.isArray(v) && v.every(link => link && typeof link === 'object' && isId(link.to) && string(link.rel))) || !optional(body.replaces, isId) || !optional(body.sharedFrom, string) || !optional(body.resourceKind, string))
+        return invalid('Invalid item extension fields');
+    return valid();
+}
+export function validateComment(body) {
+    if (!isId(body.id) || !isId(body.item) || !isId(body.onVersion) || !string(body.author) || !authored(body.authoredBy) || !string(body.at) || !optional(body.inReplyTo, isId) || !string(body.body))
+        return invalid('Invalid comment fields');
+    return valid();
+}
+export function validateDelete(body) { return isId(body.target) ? valid() : invalid('Invalid deletion target'); }
+export const itemDefinitions = [
+    { name: 'item', version: 1, validate: validateItem },
+    { name: 'comment', version: 1, validate: validateComment },
+    { name: 'delete', version: 1, validate: validateDelete },
+];
+export function parseRecord(record, definitions = itemDefinitions) {
+    if (typeof record?.type !== 'string' || !Number.isSafeInteger(record.typeVersion) || !record.body || typeof record.body !== 'object' || Array.isArray(record.body))
+        throw new Error('Invalid record');
+    const versions = definitions.filter(d => d.name === record.type);
+    let current = record;
+    let definition = versions.find(d => d.version === current.typeVersion);
+    if (!definition)
+        return { kind: 'unknown', raw: record };
+    while (definition) {
+        const result = definition.validate(current.body);
+        if (!result.ok)
+            throw new Error(result.reason);
+        const next = versions.find(d => d.version === current.typeVersion + 1);
+        if (!next?.upgrade)
+            break;
+        current = { ...current, typeVersion: next.version, body: next.upgrade(current.body) };
+        definition = next;
+    }
+    return { kind: 'known', record: current };
+}
+export function serializeRecord(parsed) { return parsed.kind === 'known' ? parsed.record : parsed.raw; }

package/dist/keys.d.ts

@@ -0,0 +1,20 @@
+import type { Identity, Recipient } from 'age-encryption';
+export type AgeRecipient = string | Recipient;
+export type AgeIdentity = string | CryptoKey | Identity;
+export interface SigningIdentity {
+    publicKey: string;
+    privateKey: string;
+}
+export declare function createAgentIdentity(): Promise<{
+    privateKey: CryptoKey;
+    recipient: string;
+}>;
+export declare function createAgeIdentity(): Promise<{
+    identity: string;
+    recipient: string;
+}>;
+export declare function deriveRecipient(identity: AgeIdentity): Promise<string>;
+export declare function createSigningIdentity(): Promise<SigningIdentity>;
+export declare function importSigningKey(privateKey: string): Promise<CryptoKey>;
+export declare function sealIdentity(identity: string, recipients: AgeRecipient[]): Promise<string>;
+export declare function openIdentity(ciphertext: string, identities: AgeIdentity[]): Promise<string>;

package/dist/keys.js

@@ -0,0 +1,36 @@
+import * as age from 'age-encryption';
+import { asBuffer, decode, encode, text, utf8 } from './codec.js';
+export async function createAgentIdentity() {
+    const pair = await crypto.subtle.generateKey({ name: 'X25519' }, false, ['deriveBits']);
+    return { privateKey: pair.privateKey, recipient: await age.identityToRecipient(pair.privateKey) };
+}
+export async function createAgeIdentity() {
+    const identity = await age.generateIdentity();
+    return { identity, recipient: await age.identityToRecipient(identity) };
+}
+export async function deriveRecipient(identity) {
+    if (typeof identity !== 'string' && !(identity instanceof CryptoKey))
+        throw new TypeError('A custom age identity cannot expose a standard recipient');
+    return age.identityToRecipient(identity);
+}
+export async function createSigningIdentity() {
+    const pair = await crypto.subtle.generateKey({ name: 'Ed25519' }, true, ['sign', 'verify']);
+    return { publicKey: encode(new Uint8Array(await crypto.subtle.exportKey('raw', pair.publicKey))), privateKey: encode(new Uint8Array(await crypto.subtle.exportKey('pkcs8', pair.privateKey))) };
+}
+export async function importSigningKey(privateKey) {
+    return crypto.subtle.importKey('pkcs8', asBuffer(decode(privateKey)), 'Ed25519', false, ['sign']);
+}
+export async function sealIdentity(identity, recipients) {
+    if (!recipients.length)
+        throw new Error('At least one recipient is required');
+    const encrypter = new age.Encrypter();
+    for (const recipient of recipients)
+        encrypter.addRecipient(recipient);
+    return encode(await encrypter.encrypt(utf8(identity)));
+}
+export async function openIdentity(ciphertext, identities) {
+    const decrypter = new age.Decrypter();
+    for (const identity of identities)
+        decrypter.addIdentity(identity);
+    return text(await decrypter.decrypt(decode(ciphertext)));
+}

package/dist/log.d.ts

@@ -0,0 +1,67 @@
+import type { JsonObject, Validation } from './types.js';
+export type Grant = 'members.manage';
+export interface Member extends JsonObject {
+    id: string;
+    recipient: string;
+    signingKey: string;
+    kind: 'person' | 'agent';
+    name?: string;
+    scope?: 'read' | 'readwrite';
+    addedBy?: string;
+    expiresAt?: string;
+    support?: true;
+}
+export declare const validAgentName: (value: unknown) => value is string;
+export interface LogEntry {
+    v: 1;
+    seq: number;
+    prev: string | null;
+    at: string;
+    actor: string;
+    type: string;
+    body: JsonObject;
+    sig: string;
+}
+export interface LogDefinition {
+    name: string;
+    fields: readonly string[];
+    validate(body: JsonObject): Validation;
+    apply?: (state: LogState, body: JsonObject, actor: string, holder: boolean) => Promise<EffectError | null>;
+}
+export interface DerivedMember {
+    member: Member;
+    grants: Grant[];
+}
+export interface LogState {
+    journey: string;
+    members: Record<string, DerivedMember>;
+    grants: Record<string, Grant[]>;
+    currentEpoch: number;
+    minClientVersion: string;
+    lastSeq: number;
+    lastHash: string | null;
+}
+export interface LogError {
+    code: 'invalid-entry' | 'broken-chain' | 'invalid-signature' | 'unauthorized' | 'last-holder' | 'client-too-old';
+    seq: number;
+    message: string;
+}
+export type LogResult = {
+    ok: true;
+    state: LogState;
+} | {
+    ok: false;
+    error: LogError;
+};
+type EffectError = {
+    code: LogError['code'];
+    message: string;
+};
+export declare const logDefinitions: readonly LogDefinition[];
+/** Canonical JSON: lexicographically sorted object keys, array order retained, UTF-8 for signing. */
+export declare function canonical(value: unknown): string;
+export declare function hashEntry(entry: LogEntry): Promise<string>;
+export declare function recipientsHash(members: LogState['members']): Promise<string>;
+export declare function signEntry(unsigned: Omit<LogEntry, 'sig'>, privateKey: CryptoKey): Promise<LogEntry>;
+export declare function verifyLog(entries: readonly LogEntry[]): Promise<LogResult>;
+export {};

package/dist/log.js

@@ -0,0 +1,201 @@
+import { isId } from './ids.js';
+import { asBuffer, decode, encode, utf8 } from './codec.js';
+import { meetsMinClientVersion } from './versions.js';
+export const validAgentName = (value) => typeof value === 'string' && value.length >= 1 && value.length <= 60 && value.trim() === value && !/[\x00-\x1f\x7f-\x9f]/.test(value);
+const denied = (message) => ({ code: 'unauthorized', message });
+function addMember(state, body, actor, holder) {
+    const member = body.member;
+    if (state.members[member.id])
+        return Promise.resolve({ code: 'invalid-entry', message: 'Duplicate member' });
+    if (member.kind === 'agent') {
+        if (member.addedBy !== actor || !state.members[member.addedBy] || body.grants.length)
+            return Promise.resolve(denied('An agent must belong to its acting person and hold no grants'));
+    }
+    else {
+        if (!holder)
+            return Promise.resolve(denied('Only a holder may add people'));
+        if (member.support && body.grants.length)
+            return Promise.resolve(denied('Support members cannot hold grants'));
+    }
+    state.members[member.id] = { member: { ...member }, grants: [...body.grants] };
+    state.grants[member.id] = [...body.grants];
+    return Promise.resolve(null);
+}
+function renameMember(state, body, actor, holder) {
+    const target = state.members[body.id]?.member;
+    if (!target || target.kind !== 'agent')
+        return Promise.resolve({ code: 'invalid-entry', message: 'Agent not found' });
+    if (!holder && target.addedBy !== actor)
+        return Promise.resolve(denied('Cannot rename another member’s agent'));
+    target.name = body.name;
+    return Promise.resolve(null);
+}
+function removeMember(state, body, actor, holder) {
+    const target = body.member;
+    const removed = state.members[target];
+    if (!removed)
+        return Promise.resolve({ code: 'invalid-entry', message: 'Member not found' });
+    if (!holder && target !== actor && removed.member.addedBy !== actor)
+        return Promise.resolve(denied('Cannot remove another member'));
+    delete state.members[target];
+    delete state.grants[target];
+    if (removed.member.kind === 'person')
+        for (const [id, value] of Object.entries(state.members))
+            if (value.member.addedBy === target) {
+                delete state.members[id];
+                delete state.grants[id];
+            }
+    return Promise.resolve(null);
+}
+function setGrant(add) {
+    return async (state, body, _actor, holder) => {
+        if (!holder)
+            return denied('Only a holder may change grants');
+        const target = body.member;
+        if (state.members[target]?.member.kind !== 'person')
+            return denied('Only people may hold grants');
+        if (state.members[target]?.member.support)
+            return denied('Support members cannot hold grants');
+        state.grants[target] = add ? ['members.manage'] : [];
+        state.members[target].grants = state.grants[target];
+        return null;
+    };
+}
+async function rotate(state, body, _actor, holder) {
+    if (!holder)
+        return denied('Only a holder may rotate keys');
+    if (body.epoch !== state.currentEpoch + 1 || body.recipientsHash !== await recipientsHash(state.members))
+        return { code: 'invalid-entry', message: 'Invalid key rotation recipients or epoch' };
+    state.currentEpoch++;
+    return null;
+}
+async function setMinimum(state, body, _actor, holder) {
+    if (!holder)
+        return denied('Only a holder may update minimum client version');
+    if (!meetsMinClientVersion(body.version, state.minClientVersion))
+        return { code: 'invalid-entry', message: 'Minimum client version cannot decrease' };
+    state.minClientVersion = body.version;
+    return null;
+}
+const ok = { ok: true };
+const fail = (reason) => ({ ok: false, reason });
+const object = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const str = (value) => typeof value === 'string' && value.length > 0;
+const shape = (body, required, allowed = required) => required.every(k => Object.hasOwn(body, k)) && Object.keys(body).every(k => allowed.includes(k));
+function validMember(value) {
+    if (!object(value) || !shape(value, ['id', 'recipient', 'signingKey', 'kind'], ['id', 'recipient', 'signingKey', 'kind', 'name', 'scope', 'addedBy', 'expiresAt', 'support']))
+        return false;
+    if (!isId(value.id) || !str(value.recipient) || !str(value.signingKey))
+        return false;
+    return value.kind === 'person' ? value.name === undefined && value.addedBy === undefined && (value.support === true ? value.scope === 'read' && typeof value.expiresAt === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value.expiresAt) && Number.isFinite(Date.parse(value.expiresAt)) : value.support === undefined && value.scope === undefined && (value.expiresAt === undefined || str(value.expiresAt))) : value.kind === 'agent' && value.support === undefined && (value.name === undefined || validAgentName(value.name)) && (value.scope === 'read' || value.scope === 'readwrite') && str(value.addedBy) && (value.expiresAt === undefined || str(value.expiresAt));
+}
+const grants = (value) => Array.isArray(value) && value.every(v => v === 'members.manage') && new Set(value).size === value.length;
+const memberBody = (body) => shape(body, ['member', 'grants', 'kind']) && validMember(body.member) && body.kind === body.member.kind && grants(body.grants) ? ok : fail('Invalid member.add');
+export const logDefinitions = [
+    { name: 'genesis', fields: ['journey', 'name', 'creator', 'grants', 'mode', 'visibility', 'minClientVersion', 'description', 'journeyKind'], validate: b => shape(b, ['journey', 'name', 'creator', 'grants', 'mode', 'visibility', 'minClientVersion'], ['journey', 'name', 'creator', 'grants', 'mode', 'visibility', 'minClientVersion', 'description', 'journeyKind']) && isId(b.journey) && str(b.name) && validMember(b.creator) && b.creator.kind === 'person' && grants(b.grants) && b.grants.includes('members.manage') && b.mode === 'sealed' && b.visibility === 'private' && str(b.minClientVersion) && (b.description === undefined || typeof b.description === 'string' && b.description.length <= 2000) && (b.journeyKind === undefined || b.journeyKind === 'individual' || b.journeyKind === 'team') ? ok : fail('Invalid genesis') },
+    { name: 'member.add', fields: ['member', 'grants', 'kind'], validate: memberBody, apply: addMember },
+    { name: 'member.rename', fields: ['id', 'name'], validate: b => shape(b, ['id', 'name']) && isId(b.id) && validAgentName(b.name) ? ok : fail('Invalid member.rename'), apply: renameMember },
+    { name: 'member.remove', fields: ['member'], validate: b => shape(b, ['member']) && isId(b.member) ? ok : fail('Invalid member.remove'), apply: removeMember },
+    { name: 'grant.add', fields: ['member', 'grant'], validate: b => shape(b, ['member', 'grant']) && isId(b.member) && b.grant === 'members.manage' ? ok : fail('Invalid grant.add'), apply: setGrant(true) },
+    { name: 'grant.remove', fields: ['member', 'grant'], validate: b => shape(b, ['member', 'grant']) && isId(b.member) && b.grant === 'members.manage' ? ok : fail('Invalid grant.remove'), apply: setGrant(false) },
+    { name: 'key.rotate', fields: ['epoch', 'recipientsHash'], validate: b => shape(b, ['epoch', 'recipientsHash']) && Number.isSafeInteger(b.epoch) && str(b.recipientsHash) ? ok : fail('Invalid key.rotate'), apply: rotate },
+    { name: 'client.minVersion', fields: ['version'], validate: b => shape(b, ['version']) && str(b.version) ? ok : fail('Invalid client.minVersion'), apply: setMinimum },
+];
+/** Canonical JSON: lexicographically sorted object keys, array order retained, UTF-8 for signing. */
+export function canonical(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value)))
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (object(value))
+        return '{' + Object.keys(value).sort((a, b) => a < b ? -1 : a > b ? 1 : 0).map(k => JSON.stringify(k) + ':' + canonical(value[k])).join(',') + '}';
+    throw new TypeError('Non-JSON value in signed log');
+}
+export async function hashEntry(entry) {
+    return encode(new Uint8Array(await crypto.subtle.digest('SHA-256', asBuffer(utf8(canonical(entry))))));
+}
+export async function recipientsHash(members) {
+    const sorted = Object.values(members).map(({ member }) => [member.id, member.recipient]).sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+    return encode(new Uint8Array(await crypto.subtle.digest('SHA-256', asBuffer(utf8(canonical(sorted))))));
+}
+function copyMember(member) {
+    const result = { id: member.id, recipient: member.recipient, signingKey: member.signingKey, kind: member.kind };
+    for (const field of ['name', 'scope', 'addedBy', 'expiresAt', 'support'])
+        if (Object.hasOwn(member, field))
+            result[field] = member[field];
+    return result;
+}
+export async function signEntry(unsigned, privateKey) {
+    const definition = logDefinitions.find(d => d.name === unsigned.type);
+    if (!definition)
+        throw new Error('Cannot sign an unknown membership entry');
+    const body = {};
+    for (const field of definition.fields)
+        if (Object.hasOwn(unsigned.body, field)) {
+            const value = unsigned.body[field];
+            body[field] = (field === 'creator' || field === 'member' && object(value)) && object(value) ? copyMember(value) : field === 'grants' && Array.isArray(value) ? [...value] : value;
+        }
+    const validation = definition.validate(body);
+    if (!validation.ok)
+        throw new Error(validation.reason);
+    const message = { v: unsigned.v, seq: unsigned.seq, prev: unsigned.prev, at: unsigned.at, actor: unsigned.actor, type: unsigned.type, body };
+    const sig = encode(new Uint8Array(await crypto.subtle.sign('Ed25519', privateKey, asBuffer(utf8(canonical(message))))));
+    return { ...message, sig };
+}
+function error(code, seq, message) { return { ok: false, error: { code, seq, message } }; }
+export async function verifyLog(entries) {
+    if (!entries.length)
+        return error('invalid-entry', 0, 'Missing genesis');
+    let state;
+    for (let index = 0; index < entries.length; index++) {
+        const entry = entries[index];
+        if (!object(entry) || !shape(entry, ['v', 'seq', 'prev', 'at', 'actor', 'type', 'body', 'sig']) || entry.v !== 1 || !Number.isSafeInteger(entry.seq) || entry.seq !== index || entry.prev !== (state?.lastHash ?? null))
+            return error('broken-chain', index, 'Sequence or previous hash mismatch');
+        if (!str(entry.at) || !str(entry.actor) || !str(entry.type) || !object(entry.body) || !str(entry.sig))
+            return error('invalid-entry', index, 'Invalid entry fields');
+        if ((index === 0) !== (entry.type === 'genesis'))
+            return error('invalid-entry', index, 'Genesis must be the first and only genesis');
+        const definition = logDefinitions.find(d => d.name === entry.type);
+        if (index === 0) {
+            const validation = definition.validate(entry.body);
+            if (!validation.ok)
+                return error('invalid-entry', index, validation.reason);
+        }
+        const signer = index === 0 ? entry.body.creator : state?.members[entry.actor]?.member;
+        if (!signer || (index === 0 && signer.id !== entry.actor))
+            return error('unauthorized', index, 'Actor is not a current member');
+        try {
+            const publicKey = await crypto.subtle.importKey('raw', asBuffer(decode(signer.signingKey)), 'Ed25519', false, ['verify']);
+            const { sig, ...unsigned } = entry;
+            if (!await crypto.subtle.verify('Ed25519', publicKey, asBuffer(decode(sig)), asBuffer(utf8(canonical(unsigned)))))
+                return error('invalid-signature', index, 'Entry signature mismatch');
+        }
+        catch {
+            return error('invalid-signature', index, 'Invalid signature or signing key');
+        }
+        if (!definition)
+            return error('client-too-old', index, 'Unknown membership entry type: ' + entry.type);
+        if (index !== 0) {
+            const validation = definition.validate(entry.body);
+            if (!validation.ok)
+                return error('invalid-entry', index, validation.reason);
+        }
+        if (index === 0) {
+            const member = entry.body.creator;
+            state = { journey: entry.body.journey, members: { [member.id]: { member, grants: ['members.manage'] } }, grants: { [member.id]: ['members.manage'] }, currentEpoch: 1, minClientVersion: entry.body.minClientVersion, lastSeq: 0, lastHash: await hashEntry(entry) };
+            continue;
+        }
+        const current = state;
+        const holder = signer.kind === 'person' && current.grants[entry.actor]?.includes('members.manage');
+        if (signer.kind !== 'person')
+            return error('unauthorized', index, 'Agents cannot sign membership changes');
+        const failure = await definition.apply?.(current, entry.body, entry.actor, Boolean(holder));
+        if (failure)
+            return error(failure.code, index, failure.message);
+        if (!Object.entries(current.members).some(([id, value]) => value.member.kind === 'person' && current.grants[id]?.includes('members.manage')))
+            return error('last-holder', index, 'At least one person must retain members.manage');
+        current.lastSeq = index;
+        current.lastHash = await hashEntry(entry);
+    }
+    return { ok: true, state: state };
+}

package/dist/removal.d.ts

@@ -0,0 +1,7 @@
+import type { LogEntry, LogState } from './log.js';
+import type { JourneyKey, KeyWrap } from './teamKey.js';
+export declare function removeAndRotate(state: LogState, target: string, actor: string, signingKey: CryptoKey): Promise<{
+    entries: [LogEntry, LogEntry];
+    key: JourneyKey;
+    wraps: KeyWrap[];
+}>;

package/dist/removal.js

@@ -0,0 +1,20 @@
+import { hashEntry, recipientsHash, signEntry } from './log.js';
+import { generateJourneyKey, wrapJourneyKey } from './teamKey.js';
+export async function removeAndRotate(state, target, actor, signingKey) {
+    if (state.members[actor]?.member.kind !== 'person' || !state.grants[actor]?.includes('members.manage'))
+        throw new Error('A person with members.manage must act');
+    if (target === actor)
+        throw new Error('A remaining acting holder must complete rotation after self-removal');
+    const removed = state.members[target];
+    if (!removed)
+        throw new Error('Member not found');
+    const remaining = Object.fromEntries(Object.entries(state.members).filter(([id, value]) => id !== target && (removed.member.kind !== 'person' || value.member.addedBy !== target)));
+    if (!Object.entries(remaining).some(([id, value]) => value.member.kind === 'person' && state.grants[id]?.includes('members.manage')))
+        throw new Error('Cannot remove last holder');
+    const at = new Date().toISOString();
+    const first = await signEntry({ v: 1, seq: state.lastSeq + 1, prev: state.lastHash, at, actor, type: 'member.remove', body: { member: target } }, signingKey);
+    const key = generateJourneyKey(state.currentEpoch + 1);
+    const wraps = await wrapJourneyKey(key, Object.values(remaining).map(({ member }) => ({ id: member.id, recipient: member.recipient })));
+    const second = await signEntry({ v: 1, seq: first.seq + 1, prev: await hashEntry(first), at, actor, type: 'key.rotate', body: { epoch: key.epoch, recipientsHash: await recipientsHash(remaining) } }, signingKey);
+    return { entries: [first, second], key, wraps };
+}

package/dist/teamKey.d.ts

@@ -0,0 +1,23 @@
+import type { AgeIdentity, AgeRecipient } from './keys.js';
+export interface JourneyKey {
+    epoch: number;
+    key: Uint8Array;
+}
+export interface KeyWrap {
+    epoch: number;
+    recipient: string;
+    ciphertext: string;
+}
+export declare function generateJourneyKey(epoch?: number): JourneyKey;
+export declare function wrapJourneyKey(key: JourneyKey, recipients: {
+    id: string;
+    recipient: AgeRecipient;
+}[]): Promise<KeyWrap[]>;
+export declare function unwrapJourneyKey(wrap: KeyWrap, identity: AgeIdentity): Promise<JourneyKey>;
+export declare function rotateJourneyKey(current: JourneyKey, recipients: {
+    id: string;
+    recipient: AgeRecipient;
+}[]): Promise<{
+    key: JourneyKey;
+    wraps: KeyWrap[];
+}>;

package/dist/teamKey.js

@@ -0,0 +1,24 @@
+import { decode, encode } from './codec.js';
+import { openIdentity, sealIdentity } from './keys.js';
+export function generateJourneyKey(epoch = 1) {
+    if (!Number.isSafeInteger(epoch) || epoch < 1)
+        throw new Error('Invalid epoch');
+    return { epoch, key: crypto.getRandomValues(new Uint8Array(32)) };
+}
+export async function wrapJourneyKey(key, recipients) {
+    if (key.key.length !== 32)
+        throw new Error('Journey key must be 256 bits');
+    if (new Set(recipients.map(r => r.id)).size !== recipients.length)
+        throw new Error('Duplicate recipient');
+    return Promise.all(recipients.map(async ({ id, recipient }) => ({ epoch: key.epoch, recipient: id, ciphertext: await sealIdentity(encode(key.key), [recipient]) })));
+}
+export async function unwrapJourneyKey(wrap, identity) {
+    const key = decode(await openIdentity(wrap.ciphertext, [identity]));
+    if (key.length !== 32)
+        throw new Error('Invalid journey key');
+    return { epoch: wrap.epoch, key };
+}
+export async function rotateJourneyKey(current, recipients) {
+    const key = generateJourneyKey(current.epoch + 1);
+    return { key, wraps: await wrapJourneyKey(key, recipients) };
+}

package/dist/transfer.d.ts

@@ -0,0 +1,14 @@
+import type { AgeIdentity, AgeRecipient } from './keys.js';
+import type { Envelope } from './envelope.js';
+import type { LogEntry, LogState } from './log.js';
+import type { KeyWrap } from './teamKey.js';
+export interface JourneyArchive {
+    log: LogEntry[];
+    envelopes: Envelope[];
+    wraps: KeyWrap[];
+}
+export declare function exportJourney(log: LogEntry[], envelopes: Envelope[], wraps: KeyWrap[], recipients: AgeRecipient[]): Promise<string>;
+export declare function importJourney(ciphertext: string, identities: AgeIdentity[]): Promise<{
+    archive: JourneyArchive;
+    state: LogState;
+}>;

package/dist/transfer.js

@@ -0,0 +1,39 @@
+import { openIdentity, sealIdentity } from './keys.js';
+import { open } from './envelope.js';
+import { verifyLog } from './log.js';
+import { unwrapJourneyKey } from './teamKey.js';
+import { parseRecord } from './items.js';
+export async function exportJourney(log, envelopes, wraps, recipients) {
+    return sealIdentity(JSON.stringify({ log, envelopes, wraps }), recipients);
+}
+export async function importJourney(ciphertext, identities) {
+    const parsed = JSON.parse(await openIdentity(ciphertext, identities));
+    if (!parsed || typeof parsed !== 'object' || !('log' in parsed) || !Array.isArray(parsed.log) || !('envelopes' in parsed) || !Array.isArray(parsed.envelopes) || !('wraps' in parsed) || !Array.isArray(parsed.wraps))
+        throw new Error('Invalid journey archive');
+    // Untrusted archive: verify its signed history before using its wraps or contents.
+    const archive = { log: parsed.log, envelopes: parsed.envelopes, wraps: parsed.wraps };
+    const verified = await verifyLog(archive.log);
+    if (!verified.ok)
+        throw new Error(verified.error.code + ': ' + verified.error.message);
+    for (const envelope of archive.envelopes) {
+        if (!envelope?.outside || envelope.outside.journey !== verified.state.journey || envelope.outside.epoch > verified.state.currentEpoch || !Number.isSafeInteger(envelope.outside.epoch))
+            throw new Error('Invalid archive envelope metadata');
+        let opened = false;
+        for (const wrap of archive.wraps.filter(w => w.epoch === envelope.outside.epoch)) {
+            for (const identity of identities) {
+                try {
+                    const key = await unwrapJourneyKey(wrap, identity);
+                    parseRecord(await open(envelope, key));
+                    opened = true;
+                    break;
+                }
+                catch { /* try another permitted identity / wrap */ }
+            }
+            if (opened)
+                break;
+        }
+        if (!opened)
+            throw new Error('No valid key or ciphertext for archive envelope');
+    }
+    return { archive, state: verified.state };
+}

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+/** JSON values preserve extensions at each protocol boundary. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+export type JsonObject = {
+    [key: string]: JsonValue | undefined;
+};
+export type ProtocolRecord = {
+    type: string;
+    typeVersion: number;
+    body: JsonObject;
+} & JsonObject;
+export type Validation = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/versions.d.ts

@@ -0,0 +1,3 @@
+export declare const PROTOCOL_VERSION: 1;
+export declare const CLIENT_VERSION: "0.1.0";
+export declare function meetsMinClientVersion(client: string, minimum: string): boolean;

package/dist/versions.js

@@ -0,0 +1,17 @@
+export const PROTOCOL_VERSION = 1;
+export const CLIENT_VERSION = '0.1.0';
+function parts(value) {
+    if (!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(value))
+        throw new Error('Invalid client version');
+    const numbers = value.split('.').map(Number);
+    if (numbers.some(n => !Number.isSafeInteger(n)))
+        throw new Error('Invalid client version');
+    return numbers;
+}
+export function meetsMinClientVersion(client, minimum) {
+    const a = parts(client), b = parts(minimum);
+    for (let i = 0; i < 3; i++)
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    return true;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@ai-wayfinding/core",
+  "version": "0.1.1",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "test": "vitest run",
+    "test:workers": "vitest run --config vitest.workers.config.ts",
+    "test:browser": "vitest run --config vitest.browser.config.ts"
+  },
+  "dependencies": {
+    "age-encryption": "^0.3.1"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.22.0",
+    "@vitest/browser-playwright": "^4.1.11",
+    "playwright": "^1.63.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AI-Wayfinding/journey.git",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}