@tinycloud/sdk-services 3.2.5 → 3.2.6-beta.4

package/dist/kv/replication/grantPolicyTypes.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Grant lifetime and renewal contract (TC-858 Phase 2, CONTRACT.md §3). Types only; S4 implements
+ * these signatures in `grantPolicy.ts` using the constants in `contractConstants.ts`.
+ * All instants are milliseconds since epoch; all durations are milliseconds.
+ */
+/** Verified source selected by session form; `first_install` is expiry-only. */
+type ReplicaConsentSource = 
+/** Verified owner SIWE `issuedAt` with finite signed expiration and exact-space KV witness. */
+"siwe"
+/** `iat` of the oldest independently verified owner-authorizing proof, never a child leaf. */
+ | "delegation_iat"
+/** `nbf` of that same oldest owner proof; a leaf signature alone is insufficient. */
+ | "delegation_nbf"
+/** Neither: persisted first grant install time, for expiry only; never session establishment. */
+ | "first_install";
+/**
+ * Invariants: `at` is finite milliseconds and clamped to ≤ now by `clampConsentAnchor`. Second-based
+ * sources (UCAN `iat`/`nbf`) are converted ×1000 exactly once, at the authority; SIWE `issuedAt`
+ * is parsed as an ISO date. Renewals never re-anchor: only a fresh sign-in yields a new anchor.
+ */
+interface ReplicaConsentAnchor {
+    at: number;
+    source: ReplicaConsentSource;
+}
+/**
+ * Returns the eligible anchor with `at` clamped to ≤ now, or null when it is not finite.
+ * A full SIWE session with missing/invalid signed expiration or issuedAt remains unanchored;
+ * never fall through to a compact leaf or first-install timestamp. Compact-only sessions
+ * may try the same independently verified oldest owner proof's `nbf` after invalid `iat`.
+ * S4 implements this as `clampConsentAnchor` in `grantPolicy.ts`.
+ */
+type ClampConsentAnchor = (anchor: ReplicaConsentAnchor, now: number) => ReplicaConsentAnchor | null;
+/**
+ * Policy the controller passes to storage in `KVReplicaSpec.grantPolicy`. Storage stores the
+ * resulting effective expiry with the installed grant and recomputes it at open.
+ */
+interface ReplicaGrantPolicy {
+    /** Validated: 0 < grantTtlMs ≤ MAX_GRANT_TTL_MS. */
+    grantTtlMs: number;
+    /**
+     * From `ReplicationAuthority.consentAnchor()`: a full SIWE session requires an
+     * independently verified signed owner `issuedAt`, finite signed expiration and
+     * exact-space KV get+sync witness. A compact-only session instead needs the oldest
+     * independently verified owner-authorizing proof's `iat`, then its `nbf` (never a
+     * fresh child leaf minted under an old owner grant). Invalid SIWE does not fall
+     * through to compact/first-install sources.
+     * Null means no verified source; storage uses its persisted first-install time only
+     * to bound grant expiry, never as freshness proof for a session stamp. That anchor
+     * survives partition reset, purge and reinstall, and is cleared only by `deny`.
+     */
+    consentAnchor: ReplicaConsentAnchor | null;
+}
+interface EffectiveGrantExpiryInput {
+    /** The grant's signed `exp` in ms; null when it has none. */
+    signedExpiresAt: number | null;
+    installedAt: number;
+    grantTtlMs: number;
+    /** `min(consentDeadlineMs(policyAnchor), durableGateDeadline)` when browser gate is active. */
+    consentDeadline: number;
+}
+/** effective expiry = min(signed exp, installedAt + grantTtlMs, consentDeadline). */
+type EffectiveGrantExpiry = (input: EffectiveGrantExpiryInput) => number;
+/** anchor.at + CONSENT_WINDOW_MS. */
+type ConsentDeadlineMs = (anchor: ReplicaConsentAnchor) => number;
+/**
+ * Duration passed to `ReplicationAuthority.mint` as `expiryMs`:
+ * min(grantTtlMs, consentDeadline − now). The caller MUST NOT mint when the result is ≤ 0.
+ */
+type MintRemainingMs = (input: {
+    now: number;
+    grantTtlMs: number;
+    consentDeadline: number;
+}) => number;
+/**
+ * True when online-renewal should run: remaining = effectiveExpiresAt − now is STRICTLY below
+ * RENEW_BELOW_FRACTION × (effectiveExpiresAt − installedAt) (exactly 25% remaining does not
+ * renew), and now < consentDeadline. All inputs finite; otherwise false.
+ * Checked on a timer, before each sync, and at open.
+ */
+type NeedsSilentRenewal = (input: {
+    now: number;
+    installedAt: number;
+    effectiveExpiresAt: number;
+    consentDeadline: number;
+}) => boolean;
+
+export type { ClampConsentAnchor, ConsentDeadlineMs, EffectiveGrantExpiry, EffectiveGrantExpiryInput, MintRemainingMs, NeedsSilentRenewal, ReplicaConsentAnchor, ReplicaConsentSource, ReplicaGrantPolicy };

package/dist/kv/replication/grantPolicyTypes.js

@@ -0,0 +1 @@
+//# sourceMappingURL=grantPolicyTypes.js.map

package/dist/kv/replication/grantPolicyTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/kv/replication/index.cjs

@@ -1201,23 +1201,24 @@ function createKVReplication(deps) {
       if (!local && !opened?.opening && !opened?.authorityRevoked) inspected = await inspectPersistedStatus(prefix);
       local ?? (local = inspected.local);
       if (inspected.missing && !opened?.reason && !opened?.authorityRevoked && !opened?.opening && !isClosed) return void 0;
-      const revoked = opened?.authorityRevoked === true || local?.authority.state === "revoked";
+      const full = local && !("redacted" in local) ? local : void 0;
+      const revoked = opened?.authorityRevoked === true || full?.authority.state === "revoked";
       const rootUnsupported = opened?.lastError === "REPLICATION_ROOT_UNSUPPORTED";
-      const state = isClosed ? "closed" : revoked ? "revoked" : rootUnsupported ? "unavailable" : opened?.reason === "grant_missing" ? "grant_missing" : local?.coverage === "complete" && local.authority.state === "valid" ? "ready" : opened?.reason || inspected.errorCode ? "unavailable" : "idle";
+      const state = isClosed ? "closed" : revoked ? "revoked" : rootUnsupported ? "unavailable" : opened?.reason === "grant_missing" ? "grant_missing" : full?.coverage === "complete" && full.authority.state === "valid" ? "ready" : opened?.reason || inspected.errorCode ? "unavailable" : "idle";
       return {
         prefix,
         state,
         ...opened?.reason ? { reason: opened.reason } : inspected.errorCode ? { reason: "replica_unavailable" } : {},
         ...inspected.errorCode ?? opened?.lastError ? { errorCode: inspected.errorCode ?? opened?.lastError } : {},
         ...local ?? {},
-        ...revoked ? { authority: { state: "revoked", expiresAt: local?.authority.expiresAt ?? null } } : {},
+        ...revoked ? { authority: { state: "revoked", expiresAt: full?.authority.expiresAt ?? null } } : {},
         pending: {
           inFlight: records.filter((r) => r.state === "in_flight").length,
           committed: records.filter((r) => r.state === "committed").length,
           ambiguous: records.filter((r) => r.state === "ambiguous").length
         },
         pinned: pinnedKeys(snapshot, prefix, scheduler.now()),
-        lagMs: local?.lastSyncAt ? scheduler.now() - Date.parse(local.lastSyncAt) : null
+        lagMs: full?.lastSyncAt ? scheduler.now() - Date.parse(full.lastSyncAt) : null
       };
     }));
     return entries.filter((entry) => entry !== void 0);