@propustka/core 0.0.1

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@propustka/core",
+	"version": "0.0.1",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/contember/propustka.git",
+		"directory": "packages/core"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"!src/**/__tests__/**"
+	],
+	"exports": {
+		".": {
+			"bun": "./src/index.ts",
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
+	}
+}

package/src/ids.ts

@@ -0,0 +1,41 @@
+/**
+ * Generate a UUIDv7 (RFC 9562): time-sortable, 128 bits.
+ *
+ * Layout:
+ *   - bytes 0..5  : 48-bit big-endian Unix-millis timestamp
+ *   - byte  6     : version nibble `7` in the high 4 bits, random in the low 4
+ *   - byte  8     : RFC 4122 variant bits `10` in the high 2 bits, random in the low 6
+ *   - the remaining 74 bits are random (`crypto.getRandomValues`)
+ *
+ * Because the timestamp occupies the most-significant bytes, two ids generated at
+ * different milliseconds sort lexicographically in time order. No dependency.
+ */
+export function uuidv7(): string {
+	const bytes = new Uint8Array(16)
+
+	// 48-bit big-endian Unix-millis timestamp in the first 6 bytes.
+	const millis = Date.now()
+	// `millis` fits in 48 bits (well under 2^53), so the high bits are zero.
+	bytes[0] = Math.floor(millis / 0x10000000000) & 0xff
+	bytes[1] = Math.floor(millis / 0x100000000) & 0xff
+	bytes[2] = Math.floor(millis / 0x1000000) & 0xff
+	bytes[3] = Math.floor(millis / 0x10000) & 0xff
+	bytes[4] = Math.floor(millis / 0x100) & 0xff
+	bytes[5] = millis & 0xff
+
+	// Fill the remaining 10 bytes (74 usable random bits + the nibble/variant slots) with randomness.
+	const random = new Uint8Array(10)
+	crypto.getRandomValues(random)
+	bytes.set(random, 6)
+
+	// Version: high nibble of byte 6 = 0b0111 (7).
+	bytes[6] = (bytes[6]! & 0x0f) | 0x70
+	// Variant: high two bits of byte 8 = 0b10.
+	bytes[8] = (bytes[8]! & 0x3f) | 0x80
+
+	const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0'))
+
+	return `${hex[0]}${hex[1]}${hex[2]}${hex[3]}-${hex[4]}${hex[5]}-${hex[6]}${hex[7]}-${hex[8]}${hex[9]}-${hex[10]}${hex[11]}${hex[12]}${hex[13]}${
+		hex[14]
+	}${hex[15]}`
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+// @propustka/core — the one shared library: pure logic & types that must not drift
+// between @propustka/worker (implements it) and @propustka/client (consumes it).
+export * from './ids'
+export * from './permissions'
+export * from './rpc'
+export * from './types'

package/src/permissions.ts

@@ -0,0 +1,75 @@
+import type { PermissionEntry } from './types'
+
+/**
+ * Wildcard action matching. The pattern is one of:
+ *  - '*'        — matches every action
+ *  - 'prefix.*' — matches the `prefix` namespace and anything nested under it
+ *                 (e.g. 'project.*' matches 'project.read' and 'project.settings.update',
+ *                  but NOT 'projects.read' — the boundary is the dot)
+ *  - exact      — matches only that exact action string
+ *
+ * Examples:
+ *   matchAction('*', 'x.y')                          === true
+ *   matchAction('project.*', 'project.read')         === true
+ *   matchAction('project.*', 'project.settings.update') === true
+ *   matchAction('project.read', 'project.read')      === true
+ *   matchAction('project.read', 'project.write')     === false
+ *   matchAction('project.*', 'projects.read')        === false
+ */
+export function matchAction(pattern: string, action: string): boolean {
+	if (pattern === '*') {
+		return true
+	}
+	if (pattern.endsWith('.*')) {
+		// Drop the trailing '*' (keep the dot) so 'project.*' yields 'project.' —
+		// the action must start with that prefix, which enforces the dot boundary.
+		const prefix = pattern.slice(0, -1)
+		return action.startsWith(prefix)
+	}
+	return pattern === action
+}
+
+/**
+ * Does `entries` grant `action` at the given scope? Mirrors `can()` semantics exactly:
+ *  - projectScope === undefined → scope-less: ONLY entries with projectId === null satisfy.
+ *  - projectScope === <id>      → entries with projectId === null OR projectId === <id> satisfy.
+ *
+ * Within the satisfying entries, the entry's `action` is matched against the requested
+ * `action` using `matchAction` (so a wildcard entry like 'project.*' grants 'project.read').
+ */
+export function permits(entries: PermissionEntry[], action: string, projectScope?: string): boolean {
+	for (const entry of entries) {
+		const scopeOk = entry.projectId === null || entry.projectId === projectScope
+		if (scopeOk && matchAction(entry.action, action)) {
+			return true
+		}
+	}
+	return false
+}
+
+/**
+ * The set of project ids `entries` grant `action` on — the resolution behind `scopedTo()`,
+ * shared so the real SDK context and any fake/test context agree exactly:
+ *   - `null`      → unrestricted: a matching GLOBAL entry (projectId === null) exists, so the
+ *                   principal holds the action everywhere (e.g. an admin / app-wide grant);
+ *   - non-empty   → exactly the project ids of the matching project-scoped entries;
+ *   - `[]`        → no matching entry: no project access at all.
+ * A matching global entry short-circuits to `null` (it dominates any scoped entries).
+ */
+export function scopedProjects(entries: PermissionEntry[], action: string): string[] | null {
+	const ids: string[] = []
+	const seen = new Set<string>()
+	for (const entry of entries) {
+		if (!matchAction(entry.action, action)) {
+			continue
+		}
+		if (entry.projectId === null) {
+			return null
+		}
+		if (!seen.has(entry.projectId)) {
+			seen.add(entry.projectId)
+			ids.push(entry.projectId)
+		}
+	}
+	return ids
+}

package/src/rpc.ts

@@ -0,0 +1,120 @@
+import type { PermissionEntry, PrincipalType } from './types'
+
+export interface AuthenticateInput {
+	/** Self-asserted caller app id; superseded by the aud-derived app id on valid tokens. */
+	app: string
+	/** Cf-Access-Jwt-Assertion header value. */
+	token: string | null
+	/** CF_Authorization cookie value, for get-identity (users only). */
+	cookie: string | null
+	/** The app's own origin (for get-identity). */
+	origin: string | null
+	requestId: string
+}
+
+export interface ResolvedPrincipal {
+	id: string
+	type: PrincipalType
+	label: string
+	permissions: PermissionEntry[]
+	requestId: string
+}
+
+export type AuthenticateResult =
+	/** get-identity failed → explicit grants only this request (`groupsUnavailable`). */
+	| { ok: true; principal: ResolvedPrincipal; groupsUnavailable?: true }
+	| { ok: false; reason: 'missing_token' | 'invalid_token' | 'unknown_principal' | 'disabled' }
+
+export interface AuditInput {
+	app: string
+	requestId: string
+	/** NULL for capability-driven events. */
+	principalId: string | null
+	/** Snapshot — survives principal deletion (token label for capabilities). */
+	principalLabel: string
+	/** Set for capability-driven events. */
+	capabilityTokenId?: string
+	action: string
+	resourceType: string
+	resourceId?: string
+	diff?: unknown
+	metadata?: unknown
+}
+
+export interface RedeemCapabilityInput {
+	app: string
+	token: string
+	requestId: string
+}
+
+export interface CapabilityGrant {
+	action: string
+	resource: string
+}
+
+export type RedeemCapabilityResult =
+	| { ok: true; capabilities: CapabilityGrant[]; tokenId: string; label: string | null }
+	| { ok: false; reason: 'unknown' | 'expired' | 'revoked' | 'exhausted' }
+
+export interface IssueCapabilityGrant {
+	action: string
+	resource: string
+	/** Scope for the delegation check ONLY (not stored). Omitted → issuer must hold the action globally. */
+	projectId?: string | null
+}
+
+export interface IssueCapabilityInput {
+	app: string
+	/** The ISSUER's Access JWT — issuer is resolved server-side, never self-asserted. */
+	token: string | null
+	/** Issuer's CF_Authorization cookie (group-derived permissions count toward delegation too). */
+	cookie: string | null
+	origin: string | null
+	requestId: string
+	grants: IssueCapabilityGrant[]
+	label?: string
+	expiresAt?: number
+	maxUses?: number
+}
+
+export type IssueCapabilityResult =
+	/** Plaintext token returned ONCE. */
+	| { ok: true; token: string; id: string }
+	| { ok: false; reason: 'missing_token' | 'invalid_token' | 'unknown_principal' | 'disabled' | 'not_allowed' }
+
+export interface RevokeCapabilityInput {
+	app: string
+	/** The CALLER's Access JWT — the authorizer is resolved server-side, never self-asserted. */
+	token: string | null
+	/** Caller's CF_Authorization cookie (group-derived permissions count toward the revoke check). */
+	cookie: string | null
+	origin: string | null
+	requestId: string
+	/** The capability token id (the `id` returned by issueCapability), NOT the plaintext token. */
+	tokenId: string
+}
+
+export type RevokeCapabilityResult =
+	/** `revoked` is false when the token was already revoked (idempotent). */
+	| { ok: true; revoked: boolean }
+	| { ok: false; reason: 'missing_token' | 'invalid_token' | 'unknown_principal' | 'disabled' | 'not_allowed' | 'not_found' }
+
+/**
+ * The RPC contract. The Worker's `WorkerEntrypoint` `implements IamRpc`; the SDK types its
+ * binding as `Service<IamRpc>` (so the SDK never imports the Worker). Methods return plain
+ * serializable objects (RPC-friendly).
+ */
+export interface IamRpc {
+	authenticate(input: AuthenticateInput): Promise<AuthenticateResult>
+	audit(event: AuditInput): Promise<void>
+	redeemCapability(input: RedeemCapabilityInput): Promise<RedeemCapabilityResult>
+	issueCapability(input: IssueCapabilityInput): Promise<IssueCapabilityResult>
+	/**
+	 * Revoke a previously-issued capability token by id. The caller is resolved from the
+	 * forwarded Access credentials and authorized: the original issuer may always revoke;
+	 * otherwise the caller must hold every granted action globally (an admin / app-wide
+	 * operator). Idempotent — revoking an already-revoked token returns `{ ok: true,
+	 * revoked: false }`. An unknown id returns `{ ok: false, reason: 'not_found' }`.
+	 */
+	revokeCapability(input: RevokeCapabilityInput): Promise<RevokeCapabilityResult>
+}

package/src/types.ts

@@ -0,0 +1,43 @@
+export type PrincipalType = 'user' | 'service'
+
+/**
+ * Where a resolved permission entry came from. Used for debuggability in the admin UI
+ * ("why does this user have this permission?"); `can()`/`scopedTo()` ignore it.
+ *  - 'grant'             — explicit `grants` row
+ *  - 'bootstrap'         — IAM_BOOTSTRAP_ADMINS env match (resolution-time only)
+ *  - `group:${groupRef}` — IdP group → role mapping (the `<org>/<team>` ref)
+ */
+export type PermissionSource = 'grant' | 'bootstrap' | `group:${string}`
+
+export interface PermissionEntry {
+	action: string
+	/** null = global / all projects */
+	projectId: string | null
+	source: PermissionSource
+}
+
+/**
+ * Domain event apps emit. Only the app knows what changed.
+ *
+ * IMPORTANT: `diff`/`metadata` may carry sensitive values (settings can hold secrets).
+ * The app MUST redact secret material before passing them — audit storage is verbatim
+ * and long-lived; the IAM Worker stores what it receives as-is.
+ */
+export interface DomainEvent {
+	action: string
+	resourceType: string
+	resourceId?: string
+	diff?: unknown
+	metadata?: unknown
+}
+
+export interface RoleDef {
+	name: string
+	description?: string
+	permissions: string[]
+}
+
+export interface RoleSource {
+	getRole(key: string): RoleDef | undefined
+	listRoles(): Record<string, RoleDef>
+}