340 lines
23 KiB
TypeScript
340 lines
23 KiB
TypeScript
import { AgentPushError, agentPushFailure, agentPushHttpFailure, type AgentPushStage } from "./agent-push-errors.ts";
|
|
|
|
/** Browser-only push contracts. Secrets stay in page request headers, never worker messages. */
|
|
export const AGENT_PUSH_STORAGE_KEY = "sybil.agent.push.v1";
|
|
export const AGENT_PUSH_CHANGED_EVENT = "sybil-agent-push-changed";
|
|
export const agentPushCursor = (value: unknown): value is string => typeof value === "string" && /^\d{1,16}$/.test(value) && Number.isSafeInteger(Number(value));
|
|
export const agentPushUuid = (value: unknown): value is string => typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
|
|
export const agentPushSourceId = agentPushUuid;
|
|
const object = (value: unknown): Record<string, unknown> | undefined => value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
|
|
|
|
export type AgentPushConfig = {
|
|
version: 1; enabled: boolean; webPushAvailable: boolean; apnsAvailable: boolean;
|
|
sourceId: string | null; quarantined: boolean; vapidPublicKey?: string;
|
|
policy: { presenceHeartbeatMs: number; presenceLeaseMs: number };
|
|
};
|
|
export function parseAgentPushConfig(value: unknown): AgentPushConfig {
|
|
const config = object(value), policy = object(config?.policy);
|
|
if (!config || config.version !== 1 || typeof config.enabled !== "boolean" || typeof config.webPushAvailable !== "boolean"
|
|
|| typeof config.apnsAvailable !== "boolean" || (config.sourceId !== null && !agentPushSourceId(config.sourceId))
|
|
|| (config.quarantined !== undefined && typeof config.quarantined !== "boolean") || !policy
|
|
|| typeof policy.presenceHeartbeatMs !== "number" || policy.presenceHeartbeatMs < 5000 || policy.presenceHeartbeatMs > 30000
|
|
|| typeof policy.presenceLeaseMs !== "number" || policy.presenceLeaseMs < 30000 || policy.presenceLeaseMs > 120000
|
|
|| (config.webPushAvailable && config.vapidPublicKey === undefined)
|
|
|| (config.vapidPublicKey !== undefined && (typeof config.vapidPublicKey !== "string" || !/^[A-Za-z0-9_-]{87}$/.test(config.vapidPublicKey)))) {
|
|
throw new AgentPushError("The server returned invalid notification configuration. Refresh Sybil; if it continues, ask the server administrator to check Web Push configuration.");
|
|
}
|
|
return { ...config, quarantined: config.quarantined === true } as AgentPushConfig;
|
|
}
|
|
export type AgentPresence = { sequence: number; visibility: "visible" | "hidden"; focused: boolean; interacted: boolean };
|
|
/** Nonsecret identity only; the bearer is never retained with the digest. */
|
|
export async function agentPushAuthorityScope(baseUrl: string, token: string | null, origin = globalThis.location?.href): Promise<string | null> {
|
|
if (!token || !globalThis.crypto?.subtle) return null;
|
|
const base = new URL(baseUrl.replace(/\/+$/, ""), origin).href;
|
|
const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify([base, token])));
|
|
return Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, "0")).join("");
|
|
}
|
|
export class AgentPushClient {
|
|
private options: { baseUrl: string; token: () => string | null; fetch?: typeof globalThis.fetch };
|
|
constructor(options: { baseUrl: string; token: () => string | null; fetch?: typeof globalThis.fetch }) { this.options = options; }
|
|
private async request(path: string, method = "GET", body?: unknown, keepalive = false, expectedScope?: string): Promise<unknown> {
|
|
const token = this.options.token();
|
|
if (!token) throw new AgentPushError("Sign in to manage notifications.");
|
|
const controller = new AbortController(), timeout = setTimeout(() => controller.abort(), 8000);
|
|
try {
|
|
// Capture the bearer before hashing, then use that exact bearer for the
|
|
// request. A concurrent sign-in must not turn old-authority cleanup into
|
|
// a new-authority DELETE whose204 falsely clears a durable tombstone.
|
|
if (expectedScope !== undefined && expectedScope !== await agentPushAuthorityScope(this.options.baseUrl, token)) throw new AgentPushError("The signed-in server changed. Refresh and enable notifications again.");
|
|
const response = await (this.options.fetch || globalThis.fetch)(`${this.options.baseUrl.replace(/\/+$/, "")}/v1/agent${path}`, {
|
|
method, headers: { Authorization: `Bearer ${token}`, ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
|
|
...(body === undefined ? {} : { body: JSON.stringify(body) }), cache: "no-store", redirect: "error", credentials: "omit", signal: controller.signal, keepalive,
|
|
});
|
|
// Never echo server/provider bodies: they may contain endpoint or key material.
|
|
if (!response.ok) throw agentPushHttpFailure(response.status);
|
|
return response.status === 204 ? undefined : await response.json();
|
|
} catch (cause) { throw agentPushFailure(cause, "service"); }
|
|
finally { clearTimeout(timeout); }
|
|
}
|
|
async config() { return parseAgentPushConfig(await this.request("/push/config")); }
|
|
async register(id: string, subscription: PushSubscriptionJSON, expectedScope?: string) {
|
|
if (!agentPushUuid(id)) throw new Error("Invalid notification installation.");
|
|
const value = object(await this.request(`/push/installations/${id}`, "PUT", { transport: "web", enabled: true, subscription }, false, expectedScope));
|
|
if (!value || value.installationId !== id || value.transport !== "web" || value.enabled !== true || !Number.isSafeInteger(value.version) || Number(value.version) < 1) throw new AgentPushError("The Sybil server did not acknowledge the notification registration. Refresh and try again.");
|
|
}
|
|
async revoke(id: string, expectedScope?: string) {
|
|
if (!agentPushUuid(id)) throw new Error("Invalid notification installation.");
|
|
await this.request(`/push/installations/${id}`, "DELETE", undefined, false, expectedScope);
|
|
}
|
|
async presence(id: string, presence: AgentPresence, keepalive = false) {
|
|
if (!agentPushUuid(id)) throw new Error("Invalid attention session.");
|
|
await this.request(`/presence/${id}`, "PUT", presence, keepalive);
|
|
}
|
|
async retirePresence(id: string) { if (agentPushUuid(id)) await this.request(`/presence/${id}`, "DELETE", undefined, true); }
|
|
async readState() {
|
|
const value = object(await this.request("/read-state"));
|
|
if (agentPushSourceId(value?.sourceId) && agentPushCursor(value?.cursor)) return { sourceId: value.sourceId, cursor: BigInt(value.cursor).toString() };
|
|
return null;
|
|
}
|
|
}
|
|
|
|
export const MAX_AGENT_PUSH_REVOCATIONS = 16;
|
|
export type AgentPushRevocation = { installationId: string; scope: string };
|
|
export type AgentPushConsent = { version: 1; installationId: string; revision: string; scope?: string; sourceId?: string; enabled: boolean; revocationPending: boolean; pendingRevocations?: AgentPushRevocation[] };
|
|
export function parseAgentPushConsent(raw: string | null): AgentPushConsent | null {
|
|
try {
|
|
const value = object(JSON.parse(raw || "null"));
|
|
if (!(value?.version === 1 && agentPushUuid(value.installationId) && agentPushUuid(value.revision)
|
|
&& (value.scope === undefined || (typeof value.scope === "string" && /^[a-f0-9]{64}$/.test(value.scope)))
|
|
&& (value.pendingRevocations === undefined || (Array.isArray(value.pendingRevocations) && value.pendingRevocations.length <= MAX_AGENT_PUSH_REVOCATIONS
|
|
&& value.pendingRevocations.every(item => agentPushUuid(object(item)?.installationId) && typeof object(item)?.scope === "string" && /^[a-f0-9]{64}$/.test(String(object(item)?.scope)))))
|
|
&& typeof value.enabled === "boolean" && typeof value.revocationPending === "boolean")) return null;
|
|
// Keep the installation identity for cleanup when migrating old/unbound
|
|
// consent. An absent or malformed source can never authorize registration.
|
|
return { ...value, sourceId: agentPushSourceId(value.sourceId) ? value.sourceId : undefined } as AgentPushConsent;
|
|
} catch { return null; }
|
|
}
|
|
export type AgentPushView = { busy: boolean; enabled: boolean; canEnable: boolean; message: string; error: string | null };
|
|
export type PushSubscriptionHandle = Pick<PushSubscription, "toJSON" | "unsubscribe">;
|
|
type PushPlatform = {
|
|
support: () => "supported" | "unsupported" | "install" | "insecure";
|
|
permission: () => NotificationPermission;
|
|
requestPermission: () => Promise<NotificationPermission>;
|
|
subscription: () => Promise<PushSubscriptionHandle | null>;
|
|
subscribe: (publicKey: string) => Promise<PushSubscriptionHandle>;
|
|
clearNotifications: () => Promise<void>;
|
|
};
|
|
/** Explicit consent survives restarts; a revoke tombstone always wins over an older enable. */
|
|
export function createAgentPushController(options: {
|
|
api: Pick<AgentPushClient, "config" | "register" | "revoke">;
|
|
platform: PushPlatform; read: () => AgentPushConsent | null; write: (consent: AgentPushConsent) => void; remove?: () => void;
|
|
scope: () => Promise<string | null>;
|
|
uuid: () => string; lock: <T>(operation: () => Promise<T>) => Promise<T>; changed: (view: AgentPushView) => void;
|
|
}) {
|
|
let config: AgentPushConfig | null = null, busy = false, error: string | null = null, localRevocation: AgentPushConsent | null = null;
|
|
let refreshError: string | null = null;
|
|
let scope: string | null = null;
|
|
let registeredSubscription: string | null = null;
|
|
const currentConsent = () => localRevocation || options.read();
|
|
const matchesContext = (record: AgentPushConsent) => !!scope && record.scope === scope
|
|
&& agentPushSourceId(record.sourceId) && record.sourceId === config?.sourceId;
|
|
const transportAvailable = () => !!config?.enabled && config.webPushAvailable && !!config.vapidPublicKey && !config.quarantined && agentPushSourceId(config.sourceId);
|
|
const refreshContext = async () => {
|
|
const nextScope = await options.scope(), nextConfig = await options.api.config();
|
|
if (nextScope !== await options.scope()) { scope = null; config = null; throw new AgentPushError("The signed-in server changed. Refresh and enable notifications again."); }
|
|
scope = nextScope; config = nextConfig;
|
|
};
|
|
const recheckContext = async (record: AgentPushConsent) => {
|
|
await refreshContext();
|
|
return matchesContext(record) && transportAvailable();
|
|
};
|
|
const state = (): AgentPushView => {
|
|
const consent = currentConsent(), support = options.platform.support(), permission = options.platform.permission();
|
|
const available = !!scope && transportAvailable();
|
|
const cleanupFull = (consent?.pendingRevocations?.length || 0) >= MAX_AGENT_PUSH_REVOCATIONS;
|
|
const enabled = consent?.enabled === true && !consent.revocationPending && permission === "granted";
|
|
const message = support === "install" ? "On iPhone or iPad, add Sybil to your Home Screen, then enable notifications there."
|
|
: support === "insecure" ? "Notifications require a secure connection. Open Sybil over HTTPS, then try again."
|
|
: support === "unsupported" ? "This browser does not support notifications here. Use a supported browser over HTTPS."
|
|
: permission === "denied" ? "Notifications are blocked. Allow Sybil in browser site settings and allow the browser's notifications in system settings, then refresh."
|
|
: cleanupFull ? "Notification cleanup is full. Sign in to a previous server to finish removing old registrations before enabling more."
|
|
: consent?.revocationPending ? "Notifications are off here. Server removal will retry when connected."
|
|
: config?.quarantined ? "Notification delivery is paused after an Agent source change. Ask the server administrator to reconcile the source before enabling notifications."
|
|
: config?.enabled && config.webPushAvailable && !agentPushSourceId(config.sourceId) ? "The Agent notification source is not ready yet. Refresh in a moment; if it continues, ask the server administrator to check the Agent connection."
|
|
: !available ? "Notifications are not configured on this server yet."
|
|
: enabled ? "Notifications are on for this browser."
|
|
: "Get an alert for unread Agent replies when all your web sessions are inactive.";
|
|
return { busy, enabled, canEnable: !busy && available && support === "supported" && permission !== "denied" && !consent?.revocationPending && !cleanupFull, message, error: error || refreshError };
|
|
};
|
|
const publish = () => options.changed(state());
|
|
const write = (consent: AgentPushConsent) => { options.write(consent); publish(); };
|
|
const consent = (): AgentPushConsent => currentConsent() || { version: 1, installationId: options.uuid(), revision: options.uuid(), ...(scope ? { scope } : {}), enabled: false, revocationPending: false };
|
|
const retireAtOriginalAuthority = async (record: Pick<AgentPushConsent, "installationId" | "scope">) => {
|
|
if (!record.scope || record.scope !== await options.scope()) return false;
|
|
await options.api.revoke(record.installationId, record.scope);
|
|
return true;
|
|
};
|
|
const retryRevocations = async () => {
|
|
const original = currentConsent();
|
|
if (!original) return;
|
|
for (const pending of original.pendingRevocations || []) {
|
|
if (currentConsent()?.revision !== original.revision) return;
|
|
const removed = await retireAtOriginalAuthority(pending).catch(() => false);
|
|
const latest = currentConsent();
|
|
if (removed && latest?.revision === original.revision) {
|
|
write({ ...latest, pendingRevocations: (latest.pendingRevocations || []).filter(item => item.installationId !== pending.installationId || item.scope !== pending.scope) });
|
|
}
|
|
}
|
|
};
|
|
const revoke = async (record: AgentPushConsent) => {
|
|
let serverRemoved = false, subscriptionRemoved = false;
|
|
await Promise.all([
|
|
retireAtOriginalAuthority(record).then(removed => { serverRemoved = removed; }).catch(() => undefined),
|
|
options.platform.subscription().then(async subscription => { subscriptionRemoved = !subscription || await subscription.unsubscribe(); }).catch(() => undefined),
|
|
options.platform.clearNotifications().catch(() => undefined),
|
|
]);
|
|
const authority = await options.scope().catch(() => null);
|
|
const latest = currentConsent();
|
|
if (latest?.revision === record.revision && subscriptionRemoved) {
|
|
const queue = latest.pendingRevocations || [];
|
|
const archived = !!record.scope && queue.some(item => item.installationId === record.installationId && item.scope === record.scope);
|
|
const differentAuthority = record.scope && record.scope !== authority;
|
|
if (serverRemoved || archived) {
|
|
const removed = { ...latest, revocationPending: false };
|
|
try { write(removed); localRevocation = null; } catch { localRevocation = removed; }
|
|
} else if (differentAuthority && queue.length < MAX_AGENT_PUSH_REVOCATIONS) {
|
|
// Keep only the old nonsecret authority digest and ID. A current-server
|
|
// DELETE/204 is never evidence that a different server retired this ID.
|
|
const archivedRecord = { ...latest, revocationPending: false,
|
|
pendingRevocations: [...queue, { installationId: record.installationId, scope: record.scope! }] };
|
|
try { write(archivedRecord); localRevocation = null; } catch { localRevocation = latest; }
|
|
}
|
|
}
|
|
};
|
|
const invalidate = async (record: AgentPushConsent) => {
|
|
if (currentConsent()?.revision !== record.revision) {
|
|
await retireAtOriginalAuthority(record).catch(() => undefined);
|
|
return;
|
|
}
|
|
const pending = { ...record, enabled: false, revocationPending: true, revision: options.uuid() };
|
|
registeredSubscription = null;
|
|
try { write(pending); } catch { localRevocation = pending; }
|
|
await revoke(pending);
|
|
};
|
|
const disable = async () => {
|
|
error = null; refreshError = null;
|
|
const record = { ...consent(), enabled: false, revocationPending: true, revision: options.uuid() };
|
|
// Synchronous durable intent is necessary before logout clears page credentials.
|
|
registeredSubscription = null;
|
|
try { write(record); }
|
|
catch {
|
|
localRevocation = record;
|
|
// Some browsers reject setItem when full but still permit removal.
|
|
try { options.remove?.(); } catch { /* Unsubscribe/revoke below still run. */ }
|
|
error = "Browser storage is unavailable. Check that notifications are off in browser settings.";
|
|
}
|
|
busy = true; publish();
|
|
try { await options.lock(() => revoke(record)); }
|
|
catch {
|
|
// A stuck tab must not prevent logout cleanup. The server permanently
|
|
// retires this UUID, so cleanup remains safe without acquiring that lock.
|
|
await revoke(record).catch(() => undefined);
|
|
error = "Notifications are off here. Removal will retry when connected.";
|
|
}
|
|
finally { busy = false; publish(); }
|
|
};
|
|
const refresh = async (clearError = false) => {
|
|
if (busy) return;
|
|
if (clearError) error = null;
|
|
try {
|
|
await refreshContext();
|
|
await options.lock(async () => {
|
|
await retryRevocations();
|
|
let record = currentConsent();
|
|
if (!record) return;
|
|
if (record.revocationPending) { await revoke(record); return; }
|
|
if (!record.enabled) return;
|
|
if (!matchesContext(record)) { await invalidate(record); return; }
|
|
const subscription = await options.platform.subscription();
|
|
if (currentConsent()?.revision !== record.revision) return;
|
|
if (options.platform.permission() !== "granted" || !subscription) {
|
|
record = { ...record, enabled: false, revocationPending: true, revision: options.uuid() }; write(record); await revoke(record); return;
|
|
}
|
|
if (transportAvailable()) {
|
|
const serialized = JSON.stringify(subscription.toJSON());
|
|
if (registeredSubscription !== serialized) {
|
|
const matching = await recheckContext(record);
|
|
if (currentConsent()?.revision !== record.revision) return;
|
|
if (!matching) { await invalidate(record); return; }
|
|
await options.api.register(record.installationId, subscription.toJSON(), record.scope);
|
|
if (currentConsent()?.revision !== record.revision) { await retireAtOriginalAuthority(record); return; }
|
|
// A source replacement may complete while the PUT is in flight.
|
|
// Never retain that registration without a fresh source check.
|
|
try {
|
|
const stillMatching = await recheckContext(record);
|
|
if (currentConsent()?.revision !== record.revision) { await retireAtOriginalAuthority(record); return; }
|
|
if (!stillMatching) { await invalidate(record); return; }
|
|
} catch (cause) { await invalidate(record); throw cause; }
|
|
registeredSubscription = serialized;
|
|
}
|
|
}
|
|
});
|
|
refreshError = null;
|
|
} catch (cause) { refreshError = agentPushFailure(cause, "service").message; }
|
|
publish();
|
|
};
|
|
const enable = async () => {
|
|
if (!state().canEnable || state().enabled || busy || !config?.vapidPublicKey || !scope || !agentPushSourceId(config.sourceId)) return;
|
|
error = null; refreshError = null;
|
|
// Explicit revocation permanently retires the old UUID on the server. Each
|
|
// new opt-in has a new identity, so a delayed old PUT cannot resurrect it.
|
|
const record: AgentPushConsent = { version: 1, installationId: options.uuid(), revision: options.uuid(), scope, sourceId: config.sourceId,
|
|
enabled: false, revocationPending: false, pendingRevocations: currentConsent()?.pendingRevocations || [] };
|
|
const publicKey = config.vapidPublicKey;
|
|
try { options.write(record); localRevocation = null; } catch { error = "Allow browser storage before enabling notifications."; publish(); return; }
|
|
// Must execute in the original click stack, before locks, worker startup or fetches.
|
|
let permission: Promise<NotificationPermission>;
|
|
try { permission = options.platform.requestPermission(); }
|
|
catch (cause) { error = agentPushFailure(cause, "permission").message; publish(); return; }
|
|
busy = true; publish();
|
|
let stage: AgentPushStage = "permission";
|
|
try {
|
|
const decision = await permission;
|
|
if (decision !== "granted") { error = decision === "denied"
|
|
? "Notifications were not allowed. Allow Sybil in browser site settings and allow the browser's notifications in system settings, then refresh."
|
|
: "The notification prompt was dismissed. Tap Enable notifications again and choose Allow."; return; }
|
|
stage = "lock";
|
|
await options.lock(async () => {
|
|
stage = "service";
|
|
const unchanged = () => options.read()?.revision === record.revision;
|
|
if (!unchanged()) return;
|
|
const matching = await recheckContext(record);
|
|
if (!unchanged()) return;
|
|
if (!matching || config?.vapidPublicKey !== publicKey) { await invalidate(record); return; }
|
|
stage = "subscription";
|
|
const subscription = await options.platform.subscription() || await options.platform.subscribe(publicKey);
|
|
if (!unchanged()) { await subscription.unsubscribe(); return; }
|
|
// A tombstone also covers a lost registration response or failed local storage write.
|
|
const pending = { ...record, enabled: false, revocationPending: true };
|
|
try {
|
|
stage = "storage"; write(pending);
|
|
stage = "service";
|
|
const matchingBeforeRegister = await recheckContext(record);
|
|
if (!unchanged() || !matchingBeforeRegister || config?.vapidPublicKey !== publicKey) { await revoke(pending); return; }
|
|
await options.api.register(record.installationId, subscription.toJSON(), record.scope);
|
|
if (!unchanged()) { await retireAtOriginalAuthority(record); await subscription.unsubscribe(); return; }
|
|
const matchingAfterRegister = await recheckContext(record);
|
|
if (!unchanged() || !matchingAfterRegister || config?.vapidPublicKey !== publicKey) { await revoke(pending); return; }
|
|
stage = "storage"; write({ ...record, enabled: true, revocationPending: false });
|
|
registeredSubscription = JSON.stringify(subscription.toJSON());
|
|
} catch (cause) {
|
|
// Retain cleanup intent even when storage fails after subscribing.
|
|
if (options.read()?.revision === record.revision) localRevocation = pending;
|
|
await revoke(pending);
|
|
throw agentPushFailure(cause, stage);
|
|
}
|
|
});
|
|
} catch (cause) { error = agentPushFailure(cause, stage).message; }
|
|
finally { busy = false; publish(); }
|
|
};
|
|
return { state, refresh, enable, disable };
|
|
}
|
|
|
|
/** Independent ordered lease per document, including focused-but-idle and recent input. */
|
|
export function createAgentPresenceReporter(options: {
|
|
snapshot: () => { visibility: "visible" | "hidden"; focused: boolean };
|
|
send: (presence: AgentPresence, keepalive: boolean) => Promise<void>;
|
|
}) {
|
|
let sequence = 0, interaction = 0, acknowledgedInteraction = 0;
|
|
return {
|
|
interact() { interaction++; },
|
|
async report(keepalive = false, hidden = false) {
|
|
const snapshot = hidden ? { visibility: "hidden" as const, focused: false } : options.snapshot();
|
|
const capturedInteraction = interaction;
|
|
const presence = { ...snapshot, focused: snapshot.visibility === "visible" && snapshot.focused, sequence: ++sequence, interacted: capturedInteraction > acknowledgedInteraction };
|
|
await options.send(presence, keepalive);
|
|
acknowledgedInteraction = Math.max(acknowledgedInteraction, capturedInteraction);
|
|
},
|
|
};
|
|
}
|