@syncular/server 0.1.3 → 0.2.1

package/dist/segment-download.d.ts

@@ -0,0 +1,14 @@
+import type { SyncRequestContext } from './context.js';
+import type { SegmentRecord } from './segment-store.js';
+export interface SegmentDownloadRequest {
+    readonly segmentId: string;
+    /** The `X-Syncular-Scopes` header: canonical JSON of the requested map. */
+    readonly scopesHeader: string;
+}
+export interface SegmentDownloadResult {
+    readonly record: SegmentRecord;
+    readonly bytes: Uint8Array;
+    /** Response headers per §5.5. */
+    readonly headers: Record<string, string>;
+}
+export declare function handleSegmentDownload(ctx: SyncRequestContext, request: SegmentDownloadRequest): Promise<SegmentDownloadResult>;

package/dist/segment-download.js

@@ -0,0 +1,125 @@
+import { clockOf, RESOLVER_OUTAGE } from './context.js';
+import { SyncError, syncError } from './errors.js';
+import { emitEvent } from './events.js';
+import { compileSchema } from './schema.js';
+import { computeEffective, scopeDigest } from './scopes.js';
+function parseScopesHeader(header) {
+    let parsed;
+    try {
+        parsed = JSON.parse(header);
+    }
+    catch {
+        throw syncError('sync.invalid_request', 'X-Syncular-Scopes is not JSON');
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw syncError('sync.invalid_request', 'X-Syncular-Scopes must be a map');
+    }
+    const scopes = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (!Array.isArray(value) ||
+            value.some((v) => typeof v !== 'string')) {
+            throw syncError('sync.invalid_request', 'X-Syncular-Scopes values must be string lists (§0)');
+        }
+        scopes[key] = value;
+    }
+    return scopes;
+}
+export async function handleSegmentDownload(ctx, request) {
+    const events = ctx.events;
+    if (events === undefined)
+        return downloadSegment(ctx, request);
+    const clock = clockOf(ctx);
+    const startedAtMs = clock();
+    try {
+        const result = await downloadSegment(ctx, request);
+        emitEvent(events, {
+            type: 'segment.downloaded',
+            atMs: clock(),
+            partition: ctx.partition,
+            actorId: ctx.actorId,
+            segmentId: request.segmentId,
+            outcome: 'ok',
+            mediaType: result.record.mediaType,
+            bytes: result.bytes.length,
+            durationMs: clock() - startedAtMs,
+        });
+        return result;
+    }
+    catch (error) {
+        emitEvent(events, {
+            type: 'segment.downloaded',
+            atMs: clock(),
+            partition: ctx.partition,
+            actorId: ctx.actorId,
+            segmentId: request.segmentId,
+            outcome: 'error',
+            errorCode: error instanceof SyncError ? error.code : 'internal',
+            durationMs: clock() - startedAtMs,
+        });
+        throw error;
+    }
+}
+async function downloadSegment(ctx, request) {
+    const entry = await ctx.segments.get(request.segmentId);
+    if (entry === undefined || entry.record.partition !== ctx.partition) {
+        throw syncError('sync.not_found', 'unknown segment (§5.5)');
+    }
+    if (entry.record.expiresAtMs <= clockOf(ctx)()) {
+        throw syncError('sync.segment_expired', 'segment TTL elapsed — re-pull to mint fresh descriptors (§5.1)');
+    }
+    const schema = compileSchema(ctx.schema);
+    const table = schema.tables.get(entry.record.table);
+    if (table === undefined) {
+        throw syncError('sync.not_found', 'segment table no longer served');
+    }
+    const requested = parseScopesHeader(request.scopesHeader);
+    for (const [key, values] of Object.entries(requested)) {
+        if (!table.declaredVariables.has(key) || values.includes('*')) {
+            throw syncError('sync.invalid_subscription', 'invalid requested scopes (§3.2)');
+        }
+    }
+    let resolved;
+    try {
+        const allowed = await ctx.resolveScopes({
+            partition: ctx.partition,
+            actorId: ctx.actorId,
+        });
+        // §7.3.3: leases authorize sync rounds, never downloads — an outage
+        // signal here denies (re-authorization needs live scopes, §5.5).
+        resolved =
+            allowed === RESOLVER_OUTAGE ? { ok: false } : { ok: true, allowed };
+    }
+    catch (error) {
+        const events = ctx.events;
+        if (events !== undefined) {
+            emitEvent(events, {
+                type: 'scopes.resolve_failed',
+                atMs: clockOf(ctx)(),
+                partition: ctx.partition,
+                actorId: ctx.actorId,
+                phase: 'segment-download',
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+        resolved = { ok: false };
+    }
+    const outcome = computeEffective(requested, resolved);
+    if (outcome.status !== 'active') {
+        throw syncError('sync.forbidden', 'segment scopes not held (§5.5)');
+    }
+    const digest = await scopeDigest(outcome.effective);
+    if (digest !== entry.record.scopeDigest) {
+        throw syncError('sync.forbidden', 'scope digest mismatch (§3.5, §5.5)');
+    }
+    return {
+        record: entry.record,
+        bytes: entry.bytes,
+        headers: {
+            'Content-Type': 'application/octet-stream',
+            ETag: `"${entry.record.segmentId}"`,
+            'Cache-Control': 'private, max-age=0',
+            // Accept-Encoding: the body may be served compressed (§5.8).
+            Vary: 'Authorization, X-Syncular-Scopes, Accept-Encoding',
+        },
+    };
+}

package/dist/segment-store.d.ts

@@ -0,0 +1,81 @@
+export declare const DEFAULT_SEGMENT_TTL_MS: number;
+export interface SegmentMetadata {
+    readonly partition: string;
+    readonly table: string;
+    readonly schemaVersion: number;
+    readonly mediaType: 'rows' | 'sqlite';
+    readonly scopeDigest: string;
+    readonly asOfCommitSeq: number;
+    readonly rowCount: number;
+    readonly rowCursor: string | null;
+    readonly nextRowCursor: string | null;
+}
+export interface SegmentRecord extends SegmentMetadata {
+    readonly segmentId: string;
+    readonly byteLength: number;
+    readonly createdAtMs: number;
+    readonly expiresAtMs: number;
+}
+/**
+ * The §5.3 reuse key: sqlite images are not byte-deterministic, so
+ * cross-client dedup is a metadata lookup, not hash convergence — one
+ * stored image per (partition, table, schemaVersion, scope digest, pin).
+ */
+export interface SegmentFindKey {
+    readonly partition: string;
+    readonly table: string;
+    readonly schemaVersion: number;
+    readonly mediaType: 'rows' | 'sqlite';
+    readonly scopeDigest: string;
+    readonly asOfCommitSeq: number;
+}
+/**
+ * Coarse store-level counters for the admin/console read surface (TODO
+ * §2.5). Optional — a store that omits `stats()` simply cannot report them.
+ * All counts include expired-but-not-yet-evicted entries (the store's own
+ * bytes on disk), split by media type.
+ */
+export interface SegmentStoreStats {
+    readonly count: number;
+    readonly bytes: number;
+    readonly rowsSegments: number;
+    readonly sqliteSegments: number;
+    /**
+     * ADDITIVE marker — present and `true` only on stores whose counters are
+     * approximate (the S3/R2 store's LIST-free pointer accumulator, which can
+     * drift under concurrent writers or after lifecycle GC). Absent on the
+     * exact in-process stores (memory/sqlite). The admin surface carries it
+     * through so the console can label the numbers honestly.
+     */
+    readonly approximate?: boolean;
+}
+export interface SegmentStore {
+    put(metadata: SegmentMetadata, bytes: Uint8Array, nowMs: number): Promise<SegmentRecord>;
+    /** Returns expired records too — expiry is the caller's check (§5.5). */
+    get(segmentId: string): Promise<{
+        record: SegmentRecord;
+        bytes: Uint8Array;
+    } | undefined>;
+    /**
+     * Unexpired record for the §5.3 reuse key (whole-table segments only:
+     * `rowCursor` null), or undefined. Servers MUST reuse instead of
+     * rebuilding sqlite images while one exists (§5.3).
+     */
+    find(key: SegmentFindKey, nowMs: number): Promise<SegmentRecord | undefined>;
+    /** Admin/console counters (TODO §2.5) — ADDITIVE, optional. */
+    stats?(): Promise<SegmentStoreStats>;
+}
+export declare function segmentIdFor(bytes: Uint8Array): Promise<string>;
+export declare class MemorySegmentStore implements SegmentStore {
+    #private;
+    constructor(options?: {
+        ttlMs?: number;
+    });
+    put(metadata: SegmentMetadata, bytes: Uint8Array, nowMs: number): Promise<SegmentRecord>;
+    get(segmentId: string): Promise<{
+        record: SegmentRecord;
+        bytes: Uint8Array;
+    } | undefined>;
+    find(key: SegmentFindKey, nowMs: number): Promise<SegmentRecord | undefined>;
+    stats(): Promise<SegmentStoreStats>;
+}

package/dist/segment-store.js

@@ -0,0 +1,63 @@
+/**
+ * Content-addressed segment store (SPEC.md §5.1).
+ *
+ * Segments are cache entries, not durable state: identical bytes share one
+ * `segmentId` (`"sha256:" + hex`), entries expire on a TTL (default 24 h),
+ * and `get` returns expired records so the download path can distinguish
+ * `sync.segment_expired` from `sync.not_found` (§5.5).
+ */
+import { sha256Hex } from './scopes.js';
+export const DEFAULT_SEGMENT_TTL_MS = 24 * 60 * 60 * 1000;
+export async function segmentIdFor(bytes) {
+    return `sha256:${await sha256Hex(bytes)}`;
+}
+export class MemorySegmentStore {
+    #ttlMs;
+    #entries = new Map();
+    constructor(options) {
+        this.#ttlMs = options?.ttlMs ?? DEFAULT_SEGMENT_TTL_MS;
+    }
+    async put(metadata, bytes, nowMs) {
+        const segmentId = await segmentIdFor(bytes);
+        const record = {
+            ...metadata,
+            segmentId,
+            byteLength: bytes.length,
+            createdAtMs: nowMs,
+            expiresAtMs: nowMs + this.#ttlMs,
+        };
+        this.#entries.set(segmentId, { record, bytes });
+        return record;
+    }
+    async get(segmentId) {
+        return this.#entries.get(segmentId);
+    }
+    async find(key, nowMs) {
+        for (const { record } of this.#entries.values()) {
+            if (record.partition === key.partition &&
+                record.table === key.table &&
+                record.schemaVersion === key.schemaVersion &&
+                record.mediaType === key.mediaType &&
+                record.scopeDigest === key.scopeDigest &&
+                record.asOfCommitSeq === key.asOfCommitSeq &&
+                record.rowCursor === null &&
+                record.expiresAtMs > nowMs) {
+                return record;
+            }
+        }
+        return undefined;
+    }
+    async stats() {
+        let bytes = 0;
+        let rowsSegments = 0;
+        let sqliteSegments = 0;
+        for (const { record } of this.#entries.values()) {
+            bytes += record.byteLength;
+            if (record.mediaType === 'sqlite')
+                sqliteSegments += 1;
+            else
+                rowsSegments += 1;
+        }
+        return { count: this.#entries.size, bytes, rowsSegments, sqliteSegments };
+    }
+}

package/dist/signed-url.d.ts

@@ -0,0 +1,139 @@
+export interface SignedUrlConfig {
+    /** HMAC key (raw bytes or UTF-8 string). */
+    readonly key: string | Uint8Array;
+    /** URL prefix; the segment URL is `${baseUrl}/${segmentId}?st=${token}`. */
+    readonly baseUrl: string;
+    /** Token TTL; SHOULD be ≤ 15 minutes (§5.4). Default 900. */
+    readonly ttlSeconds?: number;
+    /**
+     * Opaque per-partition audience (§5.4): stable per partition, MUST NOT
+     * disclose the internal partition id.
+     */
+    readonly audience: (partition: string) => string;
+}
+/** What descriptor emission needs: the §5.4 `url`/`urlExpiresAtMs` pair. */
+export interface SegmentUrlIssue {
+    readonly url: string;
+    readonly urlExpiresAtMs: number;
+}
+export interface SegmentPresignArgs {
+    readonly segmentId: string;
+    readonly partition: string;
+    readonly scopeDigest: string;
+    readonly nowMs: number;
+    /** Resolved TTL (config value or the 900 s default) — already applied. */
+    readonly ttlSeconds: number;
+}
+/**
+ * Delegated presign (§5.4): the provider signs the URL. The callback MUST
+ * satisfy the equivalence rule — the signed object key embeds exactly one
+ * `segmentId`, and `urlExpiresAtMs` reflects the real provider expiry.
+ * `S3SegmentStore.presignSegmentGet` (via `s3PresignedUrls`) is the
+ * in-tree implementation.
+ */
+export interface DelegatedPresignConfig {
+    readonly presign: (args: SegmentPresignArgs) => SegmentUrlIssue | Promise<SegmentUrlIssue>;
+    /** URL TTL; SHOULD be ≤ 15 minutes (§5.4). Default 900. */
+    readonly ttlSeconds?: number;
+}
+/** Either §5.4 scheme; the pull emits descriptors identically for both. */
+export type SegmentUrlConfig = SignedUrlConfig | DelegatedPresignConfig;
+/**
+ * Issue the §5.4 `url`/`urlExpiresAtMs` pair for one segment descriptor,
+ * routing to the native HMAC token or the delegated presigner. Callers
+ * (the pull) invoke this only after scope resolution and only when the
+ * client advertised accept bit 3.
+ */
+export declare function issueSegmentUrl(config: SegmentUrlConfig, args: {
+    readonly segmentId: string;
+    readonly partition: string;
+    readonly scopeDigest: string;
+    readonly nowMs: number;
+}): Promise<SegmentUrlIssue>;
+/**
+ * Delegated presign for BLOB downloads (§5.9.5). The blob twin of
+ * `DelegatedPresignConfig`: the provider signs the URL and the signed object
+ * key embeds the `blobId`. Issuance happens ONLY after the §5.9.5
+ * row-derived authorization check (never before), so the URL is a short-TTL
+ * bearer grant to exactly those immutable bytes — the SPEC's "authorization
+ * was resolved against the referencing rows at issuance". Unlike segments,
+ * there is no native-HMAC blob token scheme wired this rung; presign is the
+ * shipped path (`S3BlobStore.presignBlobGet` via `s3PresignedBlobUrls`).
+ */
+export interface BlobPresignArgs {
+    readonly partition: string;
+    readonly blobId: string;
+    readonly nowMs: number;
+    /** Resolved TTL (config value or the 900 s default) — already applied. */
+    readonly ttlSeconds: number;
+}
+export interface BlobPresignConfig {
+    readonly presign: (args: BlobPresignArgs) => SegmentUrlIssue | Promise<SegmentUrlIssue>;
+    /** URL TTL; SHOULD be ≤ 15 minutes (§5.9.5). Default 900. */
+    readonly ttlSeconds?: number;
+}
+/**
+ * Issue the §5.9.5 `url`/`urlExpiresAtMs` pair for one blob download. The
+ * caller (blob-handlers `downloadBlob`) invokes this only after the
+ * row-derived authorization check passes.
+ */
+export declare function issueBlobUrl(config: BlobPresignConfig, args: {
+    readonly partition: string;
+    readonly blobId: string;
+    readonly nowMs: number;
+}): Promise<SegmentUrlIssue>;
+/**
+ * Delegated presign for BLOB UPLOADS (§5.9.3 direct-to-storage). The upload
+ * twin of `BlobPresignConfig`: the provider signs a single PUT whose object
+ * key embeds the `blobId`. Issuance happens ONLY after host authentication in
+ * the upload-grant handler (uploading is host-auth-only, not scope-bearing —
+ * §5.9.3). The `byteLength` rides through so a provider MAY bind
+ * `Content-Length` (S3 conditional) to the granted size. Never a multipart or
+ * chunk protocol — single PUT only, this rung and the next (§5.9.3 non-goal).
+ * `S3BlobStore.presignBlobPut` (via `s3PresignedBlobUploads`) is the in-tree
+ * implementation.
+ */
+export interface BlobUploadPresignArgs {
+    readonly partition: string;
+    readonly blobId: string;
+    readonly byteLength: number;
+    readonly nowMs: number;
+    /** Resolved TTL (config value or the 900 s default) — already applied. */
+    readonly ttlSeconds: number;
+}
+export interface BlobUploadPresignConfig {
+    readonly presign: (args: BlobUploadPresignArgs) => SegmentUrlIssue | Promise<SegmentUrlIssue>;
+    /** URL TTL; SHOULD be ≤ 15 minutes (§5.9.3). Default 900. */
+    readonly ttlSeconds?: number;
+}
+/**
+ * Issue the §5.9.3 `url`/`urlExpiresAtMs` pair for one presigned blob upload.
+ * The caller (blob-handlers `handleBlobUploadGrant`) invokes this only after
+ * host authentication and the size-cap check against the declared byteLength.
+ */
+export declare function issueBlobUploadUrl(config: BlobUploadPresignConfig, args: {
+    readonly partition: string;
+    readonly blobId: string;
+    readonly byteLength: number;
+    readonly nowMs: number;
+}): Promise<SegmentUrlIssue>;
+export interface SegmentTokenClaims {
+    readonly v: 1;
+    readonly seg: string;
+    readonly sd: string;
+    readonly aud: string;
+    /** Unix seconds — the sole non-millisecond timestamp in the spec. */
+    readonly exp: number;
+}
+export declare function signSegmentToken(key: string | Uint8Array, claims: SegmentTokenClaims): Promise<string>;
+/**
+ * Verify a segment token per §5.4. Throws `SyncError sync.forbidden` on any
+ * failure (MAC, expiry, or claim mismatch).
+ */
+export declare function verifySegmentToken(key: string | Uint8Array, token: string, expected: {
+    readonly segmentId: string;
+    readonly scopeDigest: string;
+    readonly audience: string;
+    readonly nowMs: number;
+    readonly skewSeconds?: number;
+}): Promise<SegmentTokenClaims>;

package/dist/signed-url.js

@@ -0,0 +1,143 @@
+/**
+ * Signed-URL segment delivery (SPEC.md §5.4): the native HMAC token
+ * scheme, plus the delegated-presign alternative (S3/R2/GCS) behind one
+ * issuance seam.
+ *
+ * Native: `st = base64url(payloadJson) + "." +
+ * base64url(HMAC-SHA256(key, payloadJson))` with claims
+ * `{v, seg, sd, aud, exp}`; `exp` is unix seconds. Issuance happens inside
+ * the pull immediately after scope resolution; verification checks MAC,
+ * expiry (≤ 60 s skew), and `seg`/`sd`/`aud` equality. Actual CDN serving
+ * is out of scope.
+ *
+ * Delegated presign: the provider mints the URL (§5.4 equivalence rule —
+ * the signed object key embeds the `segmentId`, the expiry obeys the same
+ * TTL guidance); `issueSegmentUrl` routes to whichever config the host
+ * supplied. Both paths issue only after scope resolution, so a URL is
+ * never minted for scopes the actor did not hold at that moment.
+ */
+import { syncError } from './errors.js';
+/**
+ * Issue the §5.4 `url`/`urlExpiresAtMs` pair for one segment descriptor,
+ * routing to the native HMAC token or the delegated presigner. Callers
+ * (the pull) invoke this only after scope resolution and only when the
+ * client advertised accept bit 3.
+ */
+export async function issueSegmentUrl(config, args) {
+    const ttlSeconds = config.ttlSeconds ?? 900;
+    if ('presign' in config) {
+        return config.presign({ ...args, ttlSeconds });
+    }
+    const exp = Math.floor(args.nowMs / 1000) + ttlSeconds;
+    const token = await signSegmentToken(config.key, {
+        v: 1,
+        seg: args.segmentId,
+        sd: args.scopeDigest,
+        aud: config.audience(args.partition),
+        exp,
+    });
+    return {
+        url: `${config.baseUrl}/${args.segmentId}?st=${token}`,
+        urlExpiresAtMs: exp * 1000,
+    };
+}
+/**
+ * Issue the §5.9.5 `url`/`urlExpiresAtMs` pair for one blob download. The
+ * caller (blob-handlers `downloadBlob`) invokes this only after the
+ * row-derived authorization check passes.
+ */
+export async function issueBlobUrl(config, args) {
+    const ttlSeconds = config.ttlSeconds ?? 900;
+    return config.presign({ ...args, ttlSeconds });
+}
+/**
+ * Issue the §5.9.3 `url`/`urlExpiresAtMs` pair for one presigned blob upload.
+ * The caller (blob-handlers `handleBlobUploadGrant`) invokes this only after
+ * host authentication and the size-cap check against the declared byteLength.
+ */
+export async function issueBlobUploadUrl(config, args) {
+    const ttlSeconds = config.ttlSeconds ?? 900;
+    return config.presign({ ...args, ttlSeconds });
+}
+const encoder = new TextEncoder();
+// Runtime-neutral base64url (no `Buffer` — Workers/Deno/browser safe; TODO
+// §4.2): `btoa`/`atob` operate on binary strings, present in every runtime.
+function base64url(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary)
+        .replaceAll('+', '-')
+        .replaceAll('/', '_')
+        .replace(/=+$/, '');
+}
+function fromBase64url(text) {
+    const binary = atob(text.replaceAll('-', '+').replaceAll('_', '/'));
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+async function hmac(key, payload) {
+    const keyBytes = typeof key === 'string' ? encoder.encode(key) : key;
+    const cryptoKey = await crypto.subtle.importKey('raw', keyBytes.slice().buffer, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const mac = await crypto.subtle.sign('HMAC', cryptoKey, payload.slice().buffer);
+    return new Uint8Array(mac);
+}
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= (a[i] ?? 0) ^ (b[i] ?? 0);
+    return diff === 0;
+}
+export async function signSegmentToken(key, claims) {
+    const payloadJson = JSON.stringify({
+        v: claims.v,
+        seg: claims.seg,
+        sd: claims.sd,
+        aud: claims.aud,
+        exp: claims.exp,
+    });
+    const payload = encoder.encode(payloadJson);
+    const mac = await hmac(key, payload);
+    return `${base64url(payload)}.${base64url(mac)}`;
+}
+const DEFAULT_SKEW_SECONDS = 60;
+/**
+ * Verify a segment token per §5.4. Throws `SyncError sync.forbidden` on any
+ * failure (MAC, expiry, or claim mismatch).
+ */
+export async function verifySegmentToken(key, token, expected) {
+    const forbidden = (reason) => syncError('sync.forbidden', `segment token rejected: ${reason}`);
+    const dot = token.indexOf('.');
+    if (dot < 0)
+        throw forbidden('malformed token');
+    const payload = fromBase64url(token.slice(0, dot));
+    const mac = fromBase64url(token.slice(dot + 1));
+    const computed = await hmac(key, payload);
+    if (!constantTimeEqual(mac, computed))
+        throw forbidden('bad MAC');
+    let claims;
+    try {
+        claims = JSON.parse(new TextDecoder().decode(payload));
+    }
+    catch {
+        throw forbidden('unparseable claims');
+    }
+    if (claims.v !== 1)
+        throw forbidden('unsupported token version');
+    const skew = expected.skewSeconds ?? DEFAULT_SKEW_SECONDS;
+    if (typeof claims.exp !== 'number' ||
+        claims.exp < expected.nowMs / 1000 - skew) {
+        throw forbidden('token expired');
+    }
+    if (claims.seg !== expected.segmentId)
+        throw forbidden('segment mismatch');
+    if (claims.sd !== expected.scopeDigest)
+        throw forbidden('scope-digest mismatch');
+    if (claims.aud !== expected.audience)
+        throw forbidden('audience mismatch');
+    return claims;
+}

package/dist/sigv4.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Minimal AWS Signature Version 4 — exactly the subset the S3 segment
+ * store needs (header-signed requests and presigned GET URLs), hand-rolled
+ * per the dependency-light doctrine (REVISE): SigV4 is small and
+ * well-specified, so no SDK.
+ *
+ * Runtime-neutral (TODO §4.2): the crypto primitives are Web Crypto
+ * (`crypto.subtle`), not `node:crypto`, so this module runs unchanged on
+ * Cloudflare Workers / Deno / browsers as well as Bun/Node. `crypto.subtle`
+ * is async, so signing is async throughout; the `S3SegmentStore` consumers
+ * are already async, and the `DelegatedPresignConfig.presign` seam already
+ * accepts a `Promise<SegmentUrlIssue>`.
+ *
+ * Pinned by the published AWS SigV4 example vectors in
+ * `test/sigv4.test.ts`; the hermetic S3 stub re-derives every signature
+ * from the incoming request, so an asymmetric signing bug fails tests.
+ */
+export interface SigV4Credentials {
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    /** Optional STS session token (signed as `x-amz-security-token`). */
+    readonly sessionToken?: string;
+}
+/** Hex SHA-256 of an empty body — the payload hash for GET/HEAD/DELETE. */
+export declare const EMPTY_PAYLOAD_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+/** The presigned-URL payload sentinel (S3 presigns never hash the body). */
+export declare const UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
+export declare function sha256Hex(data: Uint8Array | string): Promise<string>;
+/**
+ * AWS canonical URI-encoding: RFC 3986 unreserved characters only —
+ * stricter than `encodeURIComponent` (which leaves `!'()*` alone).
+ */
+export declare function uriEncode(value: string, encodeSlash: boolean): string;
+/** `YYYYMMDD'T'HHMMSS'Z'` plus its date-only prefix, from epoch ms. */
+export declare function amzTimestamps(nowMs: number): {
+    amzDate: string;
+    dateStamp: string;
+};
+/** Sorted, fully re-encoded canonical query string from *decoded* pairs. */
+export declare function canonicalQuery(params: Iterable<readonly [string, string]>): string;
+export interface CanonicalRequestArgs {
+    readonly method: string;
+    /** The URI-encoded absolute path exactly as sent on the request line. */
+    readonly canonicalPath: string;
+    /** Decoded query pairs; `X-Amz-Signature` must already be excluded. */
+    readonly query: Iterable<readonly [string, string]>;
+    /** Only the headers being signed (name → raw value). */
+    readonly headers: Readonly<Record<string, string>>;
+    readonly payloadHash: string;
+}
+export declare function canonicalRequest(args: CanonicalRequestArgs): {
+    text: string;
+    signedHeaders: string;
+};
+export declare function stringToSign(amzDate: string, scope: string, canonicalRequestText: string): Promise<string>;
+export declare function sigV4Signature(args: {
+    readonly secretAccessKey: string;
+    readonly dateStamp: string;
+    readonly region: string;
+    readonly service: string;
+    readonly stringToSign: string;
+}): Promise<string>;
+export interface SignRequestArgs {
+    readonly method: string;
+    /** Full request URL (host is taken from here and always signed). */
+    readonly url: URL;
+    readonly region: string;
+    /** Defaults to `s3`. */
+    readonly service?: string;
+    readonly credentials: SigV4Credentials;
+    readonly nowMs: number;
+    /** Hex SHA-256 of the request body (`EMPTY_PAYLOAD_SHA256` if none). */
+    readonly payloadHash: string;
+    /** Extra headers to send *and* sign (e.g. content-type, x-amz-meta-*). */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/**
+ * Headers for a header-authenticated request: the caller's headers plus
+ * `x-amz-date`, `x-amz-content-sha256`, optional `x-amz-security-token`,
+ * and `authorization`. `host` is signed but not returned — fetch derives
+ * it from the URL.
+ */
+export declare function signRequest(args: SignRequestArgs): Promise<Record<string, string>>;
+export interface PresignArgs {
+    /** Defaults to `GET`. */
+    readonly method?: string;
+    /** Object URL without any `X-Amz-*` query parameters. */
+    readonly url: URL;
+    readonly region: string;
+    /** Defaults to `s3`. */
+    readonly service?: string;
+    readonly credentials: SigV4Credentials;
+    readonly nowMs: number;
+    readonly expiresSeconds: number;
+}
+/** Query-authenticated (presigned) URL; only the `host` header is signed. */
+export declare function presignUrl(args: PresignArgs): Promise<URL>;