@prefig/upact 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Public entry point for `@prefig/upact`.
+ *
+ * Re-exports all spec types from `./types.js` and the `createSession`
+ * factory from `./runtime.js`. Application code imports from this entry.
+ * Adapter-internal helpers (currently `_unwrapSession`) are exported from
+ * `./internal.js` and reachable only via the `@prefig/upact/internal`
+ * subpath — see SPEC.md §7.4 and `docs/adapter-shapes.md`.
+ */
+export type { Capability, IdentityLifecycle, Upactor, UserIdentity, // deprecated alias for v0.1.x compat; removed in v0.2
+Session, AuthError, AuthErrorCode, IdentityPort, } from './types.js';
+export { createSession } from './runtime.js';
+export { SubstrateUnavailableError } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAEH,YAAY,EACX,UAAU,EACV,iBAAiB,EACjB,OAAO,EACP,YAAY,EAAE,sDAAsD;AACpE,OAAO,EACP,SAAS,EACT,aAAa,EACb,YAAY,GACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Public entry point for `@prefig/upact`.
+ *
+ * Re-exports all spec types from `./types.js` and the `createSession`
+ * factory from `./runtime.js`. Application code imports from this entry.
+ * Adapter-internal helpers (currently `_unwrapSession`) are exported from
+ * `./internal.js` and reachable only via the `@prefig/upact/internal`
+ * subpath — see SPEC.md §7.4 and `docs/adapter-shapes.md`.
+ */
+export { createSession } from './runtime.js';
+export { SubstrateUnavailableError } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC;;;;;;;;GAQG;AAaH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC"}

package/dist/internal.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Adapter-internal entry point.
+ *
+ * Importing from `@prefig/upact/internal` is a contract signal that the
+ * caller is crossing the opacity boundary `Session` is meant to enforce.
+ * Conforming adapter packages MAY import from this path to recover
+ * substrate values for substrate-side operations (e.g. `signOut`,
+ * `unloadProfile`). Application packages MUST NOT.
+ *
+ * See SPEC.md §7.4.
+ */
+export { _unwrapSession } from './runtime.js';
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AACA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/internal.js

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Adapter-internal entry point.
+ *
+ * Importing from `@prefig/upact/internal` is a contract signal that the
+ * caller is crossing the opacity boundary `Session` is meant to enforce.
+ * Conforming adapter packages MAY import from this path to recover
+ * substrate values for substrate-side operations (e.g. `signOut`,
+ * `unloadProfile`). Application packages MUST NOT.
+ *
+ * See SPEC.md §7.4.
+ */
+export { _unwrapSession } from './runtime.js';
+//# sourceMappingURL=internal.js.map

package/dist/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Runtime kernel for upact.
+ *
+ * The spec (SPEC.md §7.4) requires `Session` values to be opaque to the
+ * application — applications MUST NOT decompose, decode, or extract claims
+ * from a Session. The TypeScript `Session` type alone enforces compile-time
+ * opacity (it is a branded interface that cannot be constructed in
+ * application code), but runtime opacity requires care: a naive wrapper
+ * class with a `held` field exposes the substrate value through
+ * `JSON.stringify`, `Object.keys`, `Reflect.ownKeys`, `structuredClone`,
+ * and other property-access vectors.
+ *
+ * `createSession` is the canonical factory: every conforming adapter
+ * SHOULD use it to wrap substrate session values. The returned object is
+ * frozen, has no enumerable substrate-shaped properties, returns
+ * `'[upact:session]'` from `toJSON`, and stores the substrate value in a
+ * module-private WeakMap keyed by the marker object.
+ *
+ * `_unwrapSession` is the controlled escape hatch — adapters that need to
+ * recover the substrate value (for example, to pass it back to the
+ * substrate's logout API in `invalidate`) import it from
+ * `@prefig/upact/internal`. The `/internal` import path is the contract
+ * signal that this code is crossing the opacity boundary the spec is
+ * trying to maintain. Application code MUST NOT import from
+ * `@prefig/upact/internal`.
+ *
+ * See SPEC.md §7.4 for the normative rule and `docs/adapter-shapes.md`
+ * for the cross-substrate context.
+ */
+import type { Session } from './types.js';
+/**
+ * Wrap a substrate session value into an upact-typed opaque Session.
+ *
+ * Adapter authors call this once per successful `authenticate` call;
+ * the returned `Session` satisfies §7.4 by construction.
+ */
+export declare function createSession<T>(substrateValue: T): Session;
+/**
+ * Recover the substrate value from a Session created by `createSession`
+ * in this same process. Returns `undefined` for values not produced by
+ * this factory (including sessions produced before a process restart,
+ * since the WeakMap is process-local).
+ *
+ * Adapter-internal — applications MUST NOT import this.
+ */
+export declare function _unwrapSession<T>(session: Session): T | undefined;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAI1C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,GAAG,OAAO,CAW3D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,CAAC,GAAG,SAAS,CAEjE"}

package/dist/runtime.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Runtime kernel for upact.
+ *
+ * The spec (SPEC.md §7.4) requires `Session` values to be opaque to the
+ * application — applications MUST NOT decompose, decode, or extract claims
+ * from a Session. The TypeScript `Session` type alone enforces compile-time
+ * opacity (it is a branded interface that cannot be constructed in
+ * application code), but runtime opacity requires care: a naive wrapper
+ * class with a `held` field exposes the substrate value through
+ * `JSON.stringify`, `Object.keys`, `Reflect.ownKeys`, `structuredClone`,
+ * and other property-access vectors.
+ *
+ * `createSession` is the canonical factory: every conforming adapter
+ * SHOULD use it to wrap substrate session values. The returned object is
+ * frozen, has no enumerable substrate-shaped properties, returns
+ * `'[upact:session]'` from `toJSON`, and stores the substrate value in a
+ * module-private WeakMap keyed by the marker object.
+ *
+ * `_unwrapSession` is the controlled escape hatch — adapters that need to
+ * recover the substrate value (for example, to pass it back to the
+ * substrate's logout API in `invalidate`) import it from
+ * `@prefig/upact/internal`. The `/internal` import path is the contract
+ * signal that this code is crossing the opacity boundary the spec is
+ * trying to maintain. Application code MUST NOT import from
+ * `@prefig/upact/internal`.
+ *
+ * See SPEC.md §7.4 for the normative rule and `docs/adapter-shapes.md`
+ * for the cross-substrate context.
+ */
+const SESSIONS = new WeakMap();
+/**
+ * Wrap a substrate session value into an upact-typed opaque Session.
+ *
+ * Adapter authors call this once per successful `authenticate` call;
+ * the returned `Session` satisfies §7.4 by construction.
+ */
+export function createSession(substrateValue) {
+    const marker = Object.create(null);
+    Object.defineProperty(marker, 'toJSON', {
+        value: () => '[upact:session]',
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+    SESSIONS.set(marker, substrateValue);
+    Object.freeze(marker);
+    return marker;
+}
+/**
+ * Recover the substrate value from a Session created by `createSession`
+ * in this same process. Returns `undefined` for values not produced by
+ * this factory (including sessions produced before a process restart,
+ * since the WeakMap is process-local).
+ *
+ * Adapter-internal — applications MUST NOT import this.
+ */
+export function _unwrapSession(session) {
+    return SESSIONS.get(session);
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,MAAM,QAAQ,GAAG,IAAI,OAAO,EAAmB,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAI,cAAiB;IACjD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAW,CAAC;IAC7C,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE;QACvC,KAAK,EAAE,GAAG,EAAE,CAAC,iBAAiB;QAC9B,UAAU,EAAE,KAAK;QACjB,QAAQ,EAAE,KAAK;QACf,YAAY,EAAE,KAAK;KACnB,CAAC,CAAC;IACH,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACrC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACtB,OAAO,MAA4B,CAAC;AACrC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAI,OAAgB;IACjD,OAAO,QAAQ,CAAC,GAAG,CAAC,OAA4B,CAAkB,CAAC;AACpE,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * upact — identity port v0.1
+ *
+ * Reference TypeScript types for the identity port specification.
+ * See SPEC.md in this repo for the normative document.
+ */
+/**
+ * A self-described provider feature. The application branches on capability
+ * presence; it never branches on substrate identity or provider type.
+ *
+ * The vocabulary is intentionally minimal (SPEC.md §5.1, F1). Providers do
+ * not expand it pre-emptively; new capabilities land via §5.2 extension when
+ * concrete consumers surface. Applications SHOULD treat unknown capabilities
+ * as absent.
+ *
+ * v0.1 vocabulary: only `email` and `recovery` — what shipped consumers gate
+ * on. Additional capabilities (messaging, p2p_matching, etc.) land when an
+ * adopter needs them.
+ */
+export type Capability = 'email' | 'recovery';
+/**
+ * Session lifecycle metadata. Surfaced when the substrate provides an
+ * explicit TTL (OIDC JWT `exp` claim, session-cookie `Max-Age`). Providers
+ * that have no intrinsic expiry omit this field. See SPEC.md §8.
+ */
+export interface IdentityLifecycle {
+    /** Absolute expiry time. Omitted for substrates with no intrinsic TTL. */
+    expires_at?: Date;
+    /**
+     * How the identity can be renewed once `expires_at` is reached.
+     * - `'reauth'` — full credential exchange required (OIDC, password re-entry).
+     * - `'represence'` — presence renewal suffices (P2P presence-based substrates).
+     * - `'never'` — identity does not expire.
+     */
+    renewable: 'reauth' | 'represence' | 'never';
+}
+/**
+ * The application's view of "who is this." Opaque, capability-negotiated,
+ * privacy-bounded by construction.
+ *
+ * No email, phone, legal name, IP, or device identifier appears here.
+ * Providers MUST strip such fields from their substrate before returning an
+ * Upactor. See SPEC.md §7 for the privacy minima.
+ */
+export interface Upactor {
+    /** Opaque, stable for the lifetime of this identity. Compare by equality only. */
+    id: string;
+    /** Best-effort display string. Not unique, not a contact identifier. */
+    display_hint?: string;
+    capabilities: ReadonlySet<Capability>;
+    /**
+     * Session lifecycle metadata. Present when the substrate has an explicit TTL
+     * (e.g. OIDC JWT `exp`). Omitted for substrates with no intrinsic expiry.
+     * See SPEC.md §8 and IdentityLifecycle.
+     */
+    lifecycle?: IdentityLifecycle;
+    /**
+     * Cross-substrate provenance. Distinguishes identity sources in multi-IDP
+     * deployments. `substrate` is a short identifier ('oidc', 'supabase',
+     * 'simplex'); `instance` is the issuer URL or equivalent.
+     * Decision 6 — SPEC.md §4.4.
+     */
+    provenance?: {
+        substrate: string;
+        instance?: string;
+    };
+}
+/**
+ * Deprecated alias for compatibility with v0.1.0-draft consumers. Will be
+ * removed in v0.2. New code should use `Upactor`.
+ *
+ * @deprecated Use `Upactor` instead.
+ */
+export type UserIdentity = Upactor;
+/**
+ * A provider-shaped credential exchange result. Opaque to the application.
+ * The only valid use is to pass it back to the port (e.g. for invalidate).
+ * See SPEC.md §7.4.
+ */
+export interface Session {
+    readonly _opaque: unique symbol;
+}
+/**
+ * Port-level error vocabulary, normative per SPEC.md §6.5 (Decision 4).
+ * Adapters return one of these codes; substrate-specific detail goes in
+ * `message`. Applications branch on `code` for substrate-portable error
+ * handling.
+ */
+export type AuthErrorCode = 'credential_invalid' | 'credential_rejected' | 'substrate_unavailable' | 'identity_unavailable' | 'rate_limited' | 'auth_failed';
+export interface AuthError {
+    code: AuthErrorCode;
+    message: string;
+}
+/**
+ * The four operations every conforming provider implements.
+ * See SPEC.md §6.
+ */
+export interface IdentityPort {
+    authenticate(credential: unknown): Promise<Session | AuthError>;
+    currentUpactor(request: Request): Promise<Upactor | null>;
+    invalidate(session: Session): Promise<void>;
+    issueRenewal(identity: Upactor, evidence: unknown): Promise<Upactor | null>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB;;;;;OAKG;IACH,SAAS,EAAE,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC;CAC7C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACvB,kFAAkF;IAClF,EAAE,EAAE,MAAM,CAAC;IACX,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IACtC;;;;OAIG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B;;;;;OAKG;IACH,UAAU,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC;AAEnC;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,MAAM,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACtB,oBAAoB,GACpB,qBAAqB,GACrB,uBAAuB,GACvB,sBAAsB,GACtB,cAAc,GACd,aAAa,CAAC;AAEjB,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B,YAAY,CAAC,UAAU,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IAChE,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAC1D,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,YAAY,CACX,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,OAAO,GACf,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;CAC3B"}

package/dist/types.js

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * upact — identity port v0.1
+ *
+ * Reference TypeScript types for the identity port specification.
+ * See SPEC.md in this repo for the normative document.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC;;;;;GAKG"}

package/package.json

@@ -0,0 +1,65 @@
+{
+	"name": "@prefig/upact",
+	"version": "0.1.1",
+	"description": "upact — identity port: a typed architectural contract between a social application and any identity provider, with privacy minima as the translation rule.",
+	"license": "(CC-BY-4.0 AND Apache-2.0)",
+	"type": "module",
+	"main": "./dist/index.js",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./internal": {
+			"types": "./dist/internal.d.ts",
+			"import": "./dist/internal.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE",
+		"LICENSE-CODE",
+		"SPEC.md",
+		"ROADMAP.md",
+		"CHANGELOG.md",
+		"CONTRIBUTING.md",
+		"GOVERNANCE.md",
+		"CONFORMANCE.md",
+		"SECURITY.md"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"sideEffects": false,
+	"keywords": [
+		"identity",
+		"identity-port",
+		"anti-corruption-layer",
+		"ports-and-adapters",
+		"privacy-by-design",
+		"minimum-disclosure",
+		"ulysses-pact",
+		"open-social-awards"
+	],
+	"author": "Theodore Evans",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/prefig/upact.git"
+	},
+	"scripts": {
+		"build": "tsc",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"typecheck": "tsc --noEmit",
+		"prepublishOnly": "npm run build && npm test"
+	},
+	"devDependencies": {
+		"@types/node": "^22.0.0",
+		"typescript": "^5.0.0",
+		"vitest": "^3.0.0"
+	}
+}