@weaveprotocol/core 0.1.0

package/dist/space/space-access.js

@@ -0,0 +1,135 @@
+import { canonicalize } from '../schema/expression.js';
+import { cidFromBytes, sha256 } from '../utils/hash.js';
+import { base64UrlDecode, base64UrlEncode, utf8Encode } from '../utils/encoding.js';
+import { publicKeyToDid, didToPublicKey, P256_MULTICODEC } from '../identity/did.js';
+import { checkRole } from './roles.js';
+const READ_INFO = 'weave/space-read/v1';
+const INVITE_INFO = 'weave/space-invite/v1';
+/** A fresh secret for an invite link */
+export function generateInviteSecret() {
+    return globalThis.crypto.getRandomValues(new Uint8Array(32));
+}
+async function expand(secret, info) {
+    const material = await globalThis.crypto.subtle.importKey('raw', secret, 'HKDF', false, ['deriveBits']);
+    const bits = await globalThis.crypto.subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(0), info: utf8Encode(info) }, material, 256);
+    return new Uint8Array(bits);
+}
+/**
+ * A key pair from a secret, for one purpose. The secret is expanded under its
+ * own label first, so no two uses of one secret — nor an account seed that
+ * happened to equal it — ever give the same key.
+ */
+async function derivePair(secret, info, provider) {
+    const pair = await provider.deriveKeyPairFromSeed(await expand(secret, info));
+    const did = publicKeyToDid(await provider.exportPublicKey(pair.publicKey), P256_MULTICODEC);
+    return Object.freeze({ did, privateKey: pair.privateKey });
+}
+/** The key pair an invite link's secret stands for */
+export function deriveInviteKey(secret, provider) {
+    return derivePair(secret, INVITE_INFO, provider);
+}
+/** The read key pair of a private space, from its AES key */
+export async function deriveReadKey(spaceKey, provider) {
+    return readKeyFromSeed(await deriveReadSeed(spaceKey), provider);
+}
+/**
+ * What the read key pair is made from — one way from the space key, so
+ * holding it proves you may read without letting you decrypt anything. It is
+ * what a pass hands a node that carries a space it cannot read (`space/pass.ts`).
+ */
+export async function deriveReadSeed(spaceKey) {
+    const raw = new Uint8Array(await globalThis.crypto.subtle.exportKey('raw', spaceKey.key));
+    return expand(raw, READ_INFO);
+}
+/** The read key pair, from its seed */
+export async function readKeyFromSeed(seed, provider) {
+    const pair = await provider.deriveKeyPairFromSeed(seed);
+    const did = publicKeyToDid(await provider.exportPublicKey(pair.publicKey), P256_MULTICODEC);
+    return Object.freeze({ did, privateKey: pair.privateKey });
+}
+/** The fields of a space its id is made from */
+export function spaceGenesis(space) {
+    return {
+        v: 2,
+        creator: space.creator,
+        visibility: space.visibility,
+        roles: space.roles,
+        creatorRole: space.creatorRole,
+        createdAt: space.createdAt,
+        nonce: space.nonce,
+        ...(space.readKey ? { readKey: space.readKey } : {}),
+        ...(space.encryptionKeyId ? { encryptionKeyId: space.encryptionKeyId } : {}),
+    };
+}
+/** The id a space with this genesis has */
+export function spaceIdOf(genesis) {
+    return cidFromBytes(utf8Encode(canonicalize(genesis)));
+}
+/** Why a set of starting roles cannot found a space, or null */
+export function checkStartingRoles(roles, creatorRole) {
+    if (!Array.isArray(roles) || roles.length === 0 || roles.length > 64)
+        return 'A space starts with 1–64 roles';
+    for (const role of roles) {
+        const problem = checkRole(role);
+        if (problem)
+            return problem;
+    }
+    if (new Set(roles.map((role) => role.name)).size !== roles.length)
+        return 'Two starting roles share a name';
+    if (!roles.some((role) => role.name === creatorRole))
+        return 'The creator\'s role is not one of the starting roles';
+    return null;
+}
+/**
+ * Why a space someone handed over cannot be trusted, or null when it can:
+ * its id must be its genesis's hash, and it must have the keys its kind needs.
+ */
+export async function checkSpace(space) {
+    if (typeof space?.id !== 'string' || typeof space.nonce !== 'string' || typeof space.creator !== 'string') {
+        return 'It is missing what identifies it';
+    }
+    if (space.visibility !== 'public' && space.visibility !== 'private')
+        return 'Its visibility is not public or private';
+    const roles = checkStartingRoles(space.roles, space.creatorRole);
+    if (roles)
+        return roles;
+    if (space.visibility === 'private' && (!space.readKey || !space.encryptionKeyId))
+        return 'A private space must name its read key';
+    if (space.visibility === 'public' && (space.readKey || space.encryptionKeyId))
+        return 'A public space has no read key';
+    if ((await spaceIdOf(spaceGenesis(space))) !== space.id)
+        return 'Its id does not match what it says about itself';
+    return null;
+}
+// ─── Record keys in the access history ────────────────────────────────
+//
+// Record keys are lower case; DIDs and CIDs are not. So a key names a hash of
+// the thing, and the record's body names the thing itself.
+async function hashKey(prefix, value) {
+    const digest = await sha256(utf8Encode(value));
+    return `${prefix}:${Array.from(digest.subarray(0, 20), (b) => b.toString(16).padStart(2, '0')).join('')}`;
+}
+/** The key of an account's member record */
+export const memberKey = (did) => hashKey('member', did);
+/** The key of an invite's record, from its public key */
+export const inviteKey = (inviteDid) => hashKey('invite', inviteDid);
+/** The key of the record revoking a note, from the note's CID */
+export const revokeKey = (noteCid) => hashKey('revoke', noteCid);
+/** The key of a role's record */
+export const roleKey = (name) => `role:${name}`;
+const inviteLabel = (spaceId, did) => utf8Encode(`${INVITE_INFO}|${spaceId}|${did}`);
+/** An invite key's signature, letting `did` join `spaceId` — what a member record carries when it joins by invite */
+export async function signInvite(spaceId, did, invite, provider) {
+    return base64UrlEncode(await provider.sign(invite.privateKey, inviteLabel(spaceId, did)));
+}
+/** Whether an invite key signed for `did` to join `spaceId` */
+export async function verifyInvite(spaceId, did, inviteDid, signature, provider) {
+    try {
+        const publicKey = await provider.importPublicKey(didToPublicKey(inviteDid).publicKeyBytes);
+        return await provider.verify(publicKey, base64UrlDecode(signature), inviteLabel(spaceId, did));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=space-access.js.map

package/dist/space/space-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"space-access.js","sourceRoot":"","sources":["../../src/space/space-access.ts"],"names":[],"mappings":"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"}

package/dist/space/space-manager.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @module space-manager
+ * Spaces — the cryptographic containers everything else lives in — as this
+ * node holds them: the space, its key if it is private, and anything waiting
+ * to be done with it.
+ *
+ * A space is `public` or `private` (whether bodies are encrypted), fixed at
+ * creation. Who may write is not a property of the space but of its access
+ * history: roles and members, as records in it (`space/roles.ts`).
+ */
+import type { CryptoProvider, Space, SpaceRole, SpaceVisibility, StorageAdapter } from '../types.js';
+import { type SpaceKey } from '../privacy/space-encryption.js';
+import { type SpaceKeyPair } from './space-access.js';
+/** A space plus the secrets this node holds for it */
+export interface SpaceRecord {
+    readonly space: Space;
+    /** The AES key that reads a private space */
+    readonly key: SpaceKey | null;
+    /**
+     * An invite link's secret, held until this account's member record is
+     * written with it — which needs the invite's own record to have arrived.
+     * Null once joined, or for a view-only invite.
+     */
+    readonly invite: Uint8Array | null;
+    /** The role this account last held here, as the space's access history said — a hint for listing, not a gate */
+    readonly role: string | null;
+    /**
+     * The read key pair, for a node that carries a private space without its
+     * key (`space/pass.ts`). With the key it is derived from that instead.
+     */
+    readonly read?: SpaceKeyPair | null;
+}
+export interface CreateSpaceParams {
+    readonly name: string;
+    readonly visibility: SpaceVisibility;
+    readonly creator: string;
+    /** The roles it starts with. Default: the creator alone, holding everything (`presets.solo`). */
+    readonly roles?: ReadonlyArray<SpaceRole>;
+    readonly creatorRole?: string;
+}
+/** What an invite carries: enough to find the space, to read it if it is private, and to join it if it says so */
+export interface SpaceInvite {
+    readonly space: Space;
+    /** Raw AES key material, base64url — present only for private spaces */
+    readonly key?: string;
+    /** The invite link's secret, base64url — absent in a view-only invite */
+    readonly invite?: string;
+    /** The role the invite is for, for showing before joining. The space's own record is what counts. */
+    readonly role?: string;
+    readonly invitedBy: string;
+}
+export interface InviteOptions {
+    /** The secret behind an invite record already written for a role. Absent: a view-only invite. */
+    readonly secret?: Uint8Array;
+    readonly role?: string;
+}
+export interface SpaceManager {
+    create(params: CreateSpaceParams): Promise<SpaceRecord>;
+    get(spaceId: string): Promise<SpaceRecord | null>;
+    list(): Promise<ReadonlyArray<SpaceRecord>>;
+    remove(spaceId: string): Promise<void>;
+    /** Encodes a space, its key if private, and an invite's secret if given, as a shareable string */
+    createInvite(spaceId: string, invitedBy: string, options?: InviteOptions): Promise<string>;
+    /**
+     * Stores a space received as an invite, so it can be opened and synced.
+     * Refuses a space whose id does not match what it says about itself, and
+     * a key that does not belong to it. An invite's secret is held until it is used.
+     */
+    join(invite: string): Promise<SpaceRecord>;
+    /** Forgets an invite's secret once it has been used */
+    clearInvite(spaceId: string): Promise<void>;
+    /** Remembers the role this account holds, for listing */
+    setRole(spaceId: string, role: string | null): Promise<void>;
+}
+/**
+ * Creates a space manager backed by a storage adapter.
+ * @param adapter Where spaces and their keys are kept
+ * @returns The space manager
+ */
+export declare function createSpaceManager(adapter: StorageAdapter, provider?: CryptoProvider): SpaceManager;
+/**
+ * Decodes an invite without touching storage.
+ * @param invite The encoded invite string
+ * @returns The space it describes, and its key when private
+ */
+export declare function parseSpaceInvite(invite: string): SpaceInvite;
+//# sourceMappingURL=space-manager.d.ts.map

package/dist/space/space-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"space-manager.d.ts","sourceRoot":"","sources":["../../src/space/space-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGrG,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AACjF,OAAO,EAA2F,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAG/I,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IACnC,gHAAgH;IAChH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iGAAiG;IACjG,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,kHAAkH;AAClH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,qGAAqG;IACrG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,iGAAiG;IACjG,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACxD,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAClD,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;IAC5C,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,kGAAkG;IAClG,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3F;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3C,uDAAuD;IACvD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,yDAAyD;IACzD,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAoCD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,GAAE,cAAqC,GAAG,YAAY,CAwIzH;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAU5D"}

package/dist/space/space-manager.js

@@ -0,0 +1,187 @@
+/**
+ * @module space-manager
+ * Spaces — the cryptographic containers everything else lives in — as this
+ * node holds them: the space, its key if it is private, and anything waiting
+ * to be done with it.
+ *
+ * A space is `public` or `private` (whether bodies are encrypted), fixed at
+ * creation. Who may write is not a property of the space but of its access
+ * history: roles and members, as records in it (`space/roles.ts`).
+ */
+import { createP256Provider } from '../identity/crypto-p256.js';
+import { base64UrlEncode, base64UrlDecode, utf8Encode, utf8Decode } from '../utils/encoding.js';
+import { generateSpaceKey } from '../privacy/space-encryption.js';
+import { checkSpace, checkStartingRoles, deriveInviteKey, deriveReadKey, spaceGenesis, spaceIdOf } from './space-access.js';
+import { solo } from './presets.js';
+const SPACE_PREFIX = 'space:';
+const KEY_PREFIX = 'spacekey:';
+const INVITE_PREFIX = 'spaceinvite:';
+const ROLE_PREFIX = 'spacerole:';
+async function exportKey(key) {
+    const raw = await globalThis.crypto.subtle.exportKey('raw', key.key);
+    return {
+        id: key.id,
+        raw: base64UrlEncode(new Uint8Array(raw)),
+        createdAt: key.createdAt,
+        version: key.version,
+    };
+}
+async function importKey(stored) {
+    const key = await globalThis.crypto.subtle.importKey('raw', base64UrlDecode(stored.raw), { name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt']);
+    return Object.freeze({ id: stored.id, key, createdAt: stored.createdAt, version: stored.version });
+}
+/**
+ * Creates a space manager backed by a storage adapter.
+ * @param adapter Where spaces and their keys are kept
+ * @returns The space manager
+ */
+export function createSpaceManager(adapter, provider = createP256Provider()) {
+    async function readSpace(spaceId) {
+        const bytes = await adapter.get(`${SPACE_PREFIX}${spaceId}`);
+        return bytes ? JSON.parse(utf8Decode(bytes)) : null;
+    }
+    async function writeSpace(space) {
+        await adapter.put(`${SPACE_PREFIX}${space.id}`, utf8Encode(JSON.stringify(space)));
+    }
+    async function readKey(spaceId) {
+        const bytes = await adapter.get(`${KEY_PREFIX}${spaceId}`);
+        if (!bytes)
+            return null;
+        return importKey(JSON.parse(utf8Decode(bytes)));
+    }
+    async function writeKey(spaceId, key) {
+        const stored = await exportKey(key);
+        await adapter.put(`${KEY_PREFIX}${spaceId}`, utf8Encode(JSON.stringify(stored)));
+    }
+    async function readText(prefix, spaceId) {
+        const bytes = await adapter.get(`${prefix}${spaceId}`);
+        return bytes ? utf8Decode(bytes) : null;
+    }
+    async function load(spaceId) {
+        const space = await readSpace(spaceId);
+        if (!space)
+            return null;
+        const invite = await readText(INVITE_PREFIX, spaceId);
+        return {
+            space,
+            key: await readKey(spaceId),
+            invite: invite ? base64UrlDecode(invite) : null,
+            role: await readText(ROLE_PREFIX, spaceId),
+        };
+    }
+    return Object.freeze({
+        async create(params) {
+            const createdAt = new Date().toISOString();
+            // A nonce keeps two spaces made alike from colliding on one id.
+            const nonce = base64UrlEncode(globalThis.crypto.getRandomValues(new Uint8Array(12)));
+            const roles = params.roles ?? solo.roles;
+            const creatorRole = params.creatorRole ?? (params.roles ? [...roles].sort((a, b) => b.rank - a.rank)[0]?.name : solo.creatorRole) ?? '';
+            const problem = checkStartingRoles(roles, creatorRole);
+            if (problem)
+                throw new Error(problem);
+            const key = params.visibility === 'private' ? await generateSpaceKey() : null;
+            const fixed = {
+                visibility: params.visibility,
+                creator: params.creator,
+                roles: roles.map((role) => Object.freeze({ ...role, permissions: Object.freeze([...role.permissions]) })),
+                creatorRole,
+                createdAt,
+                nonce,
+                ...(key ? { readKey: (await deriveReadKey(key, provider)).did, encryptionKeyId: key.id } : {}),
+            };
+            const id = await spaceIdOf(spaceGenesis(fixed));
+            const space = Object.freeze({ id, ...fixed, name: params.name });
+            await writeSpace(space);
+            if (key)
+                await writeKey(id, key);
+            await adapter.put(`${ROLE_PREFIX}${id}`, utf8Encode(creatorRole));
+            return { space, key, invite: null, role: creatorRole };
+        },
+        async get(spaceId) {
+            return load(spaceId);
+        },
+        async list() {
+            const keys = await adapter.list(SPACE_PREFIX);
+            const records = await Promise.all(keys.map((key) => load(key.slice(SPACE_PREFIX.length))));
+            return records
+                .filter((record) => record !== null)
+                .sort((a, b) => a.space.createdAt.localeCompare(b.space.createdAt));
+        },
+        async remove(spaceId) {
+            for (const prefix of [SPACE_PREFIX, KEY_PREFIX, INVITE_PREFIX, ROLE_PREFIX])
+                await adapter.delete(`${prefix}${spaceId}`);
+        },
+        async createInvite(spaceId, invitedBy, options = {}) {
+            const record = await load(spaceId);
+            if (!record)
+                throw new Error(`Unknown space: ${spaceId}`);
+            // The key rides along for private spaces — which is why an invite is a
+            // secret, and why it belongs in a URL fragment rather than a path.
+            const invite = {
+                space: record.space,
+                invitedBy,
+                ...(record.key ? { key: (await exportKey(record.key)).raw } : {}),
+                ...(options.secret ? { invite: base64UrlEncode(options.secret) } : {}),
+                ...(options.secret && options.role ? { role: options.role } : {}),
+            };
+            return base64UrlEncode(utf8Encode(JSON.stringify(invite)));
+        },
+        async join(invite) {
+            const parsed = parseSpaceInvite(invite);
+            // Whoever made the invite could have edited it. The space must hash to
+            // its id, and its key must be the one the space names.
+            const problem = await checkSpace(parsed.space);
+            if (problem)
+                throw new Error(`That invite does not describe a real space: ${problem.charAt(0).toLowerCase()}${problem.slice(1)}.`);
+            const key = parsed.key
+                ? await importKey({ id: parsed.space.encryptionKeyId ?? '', raw: parsed.key, createdAt: parsed.space.createdAt, version: 1 })
+                : null;
+            if (key && (await deriveReadKey(key, provider)).did !== parsed.space.readKey) {
+                throw new Error('That invite carries a key that does not belong to its space.');
+            }
+            const secret = parsed.invite ? base64UrlDecode(parsed.invite) : null;
+            // A secret of the wrong length cannot be an invite's; refuse it here rather than wait on it forever.
+            if (secret && secret.length !== 32)
+                throw new Error('That invite carries a secret that is not an invite\'s.');
+            if (secret)
+                await deriveInviteKey(secret, provider);
+            const space = Object.freeze({ ...parsed.space });
+            await writeSpace(space);
+            if (key)
+                await writeKey(space.id, key);
+            // Joining again with a secret while one is waiting keeps the newer one.
+            if (secret)
+                await adapter.put(`${INVITE_PREFIX}${space.id}`, utf8Encode(base64UrlEncode(secret)));
+            return (await load(space.id));
+        },
+        async clearInvite(spaceId) {
+            await adapter.delete(`${INVITE_PREFIX}${spaceId}`);
+        },
+        async setRole(spaceId, role) {
+            if (!(await readSpace(spaceId)))
+                return;
+            if (role === null)
+                await adapter.delete(`${ROLE_PREFIX}${spaceId}`);
+            else
+                await adapter.put(`${ROLE_PREFIX}${spaceId}`, utf8Encode(role));
+        },
+    });
+}
+/**
+ * Decodes an invite without touching storage.
+ * @param invite The encoded invite string
+ * @returns The space it describes, and its key when private
+ */
+export function parseSpaceInvite(invite) {
+    try {
+        const parsed = JSON.parse(utf8Decode(base64UrlDecode(invite.trim())));
+        if (!parsed?.space?.id || !parsed.space.name) {
+            throw new Error('missing space');
+        }
+        return parsed;
+    }
+    catch {
+        throw new Error('That invite could not be read — it may be truncated or from another app.');
+    }
+}
+//# sourceMappingURL=space-manager.js.map

package/dist/space/space-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"space-manager.js","sourceRoot":"","sources":["../../src/space/space-manager.ts"],"names":[],"mappings":"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"}

package/dist/storage/directory-access.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @module directory-access
+ * Getting hold of the user's data folder, and getting it back on the next visit.
+ *
+ * A directory handle is the one capability a web page can hold that outlives the
+ * origin sandbox, so the browser guards it carefully: it can only be obtained
+ * from a user gesture, and permission has to be re-confirmed when a new session
+ * starts. The handle itself is structured-cloneable, which means it can be kept
+ * in IndexedDB — origin-local storage of a *pointer* to origin-independent data.
+ */
+import type { DirectoryHandleLike } from './folder-adapter.js';
+/** Read or read-write, in the browser's vocabulary */
+export type FolderAccessMode = 'read' | 'readwrite';
+/**
+ * Whether this browser can hand out a directory at all.
+ *
+ * Chrome, Edge and Opera on the desktop can. Firefox and Safari cannot, and
+ * neither can any mobile browser, so a caller has to have something else to
+ * offer — this returning false is a normal state, not a broken one.
+ *
+ * @returns Whether {@link pickDataFolder} will work here
+ */
+export declare function isFolderStorageAvailable(): boolean;
+/**
+ * Asks the user to choose their data folder. Must be called from a click.
+ *
+ * @param options.id Groups the picker's memory of where it last opened. Keeping
+ *   this stable across apps means the second view of the same data opens the
+ *   picker already pointing at the right folder.
+ * @returns The chosen directory
+ */
+export declare function pickDataFolder(options?: {
+    id?: string;
+}): Promise<DirectoryHandleLike>;
+/**
+ * Asks what this origin is currently allowed to do with a folder.
+ * @param handle The directory in question
+ * @param mode The access being asked about
+ * @returns `granted`, `denied`, or `prompt` when the user has yet to be asked
+ */
+export declare function queryFolderPermission(handle: DirectoryHandleLike, mode?: FolderAccessMode): Promise<PermissionState>;
+/**
+ * Makes sure this origin may use a folder, prompting if it has to.
+ *
+ * The prompt needs a user gesture, so `request` should only be true on a path
+ * that began with a click — call it with `false` on page load to find out
+ * whether a button needs showing at all.
+ *
+ * @param handle The directory to check
+ * @param options.request Whether to prompt when permission is not already given
+ * @param options.mode The access needed
+ * @returns Whether the folder is usable
+ */
+export declare function ensureFolderPermission(handle: DirectoryHandleLike, options?: {
+    request?: boolean;
+    mode?: FolderAccessMode;
+}): Promise<boolean>;
+/**
+ * Remembers a folder so the next visit can skip the picker.
+ *
+ * Only the handle is stored, never the contents — this origin keeps a pointer,
+ * and the data stays where the user put it.
+ *
+ * @param handle The directory to remember
+ */
+export declare function rememberDataFolder(handle: DirectoryHandleLike): Promise<void>;
+/**
+ * The folder this origin used last, if the browser still has it.
+ *
+ * Says nothing about permission — a recalled handle usually needs
+ * {@link ensureFolderPermission} with a gesture before it can be read.
+ *
+ * @returns The remembered directory, or null
+ */
+export declare function recallDataFolder(): Promise<DirectoryHandleLike | null>;
+/** Forgets the remembered folder. The folder and everything in it stay put. */
+export declare function forgetDataFolder(): Promise<void>;
+//# sourceMappingURL=directory-access.d.ts.map

package/dist/storage/directory-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-access.d.ts","sourceRoot":"","sources":["../../src/storage/directory-access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAG/D,sDAAsD;AACtD,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,WAAW,CAAC;AAkBpD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,OAAO,CAAC,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAgB5F;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,mBAAmB,EAC3B,IAAI,GAAE,gBAA8B,GACnC,OAAO,CAAC,eAAe,CAAC,CAI1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,mBAAmB,EAC3B,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,gBAAgB,CAAA;CAAE,GACvD,OAAO,CAAC,OAAO,CAAC,CAQlB;AAmBD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYnF;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAgB5E;AAED,+EAA+E;AAC/E,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAgBtD"}