@fabrika/control-contract 0.4.2 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/control-contract",
-	"version": "0.4.2",
+	"version": "0.4.3",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -25,8 +25,8 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth-core": "^0.4.2",
-		"@fabrika/app": "^0.4.2",
-		"@fabrika/provider-contract": "^0.4.2"
+		"@fabrika/auth-core": "^0.4.3",
+		"@fabrika/app": "^0.4.3",
+		"@fabrika/provider-contract": "^0.4.3"
 	}
 }

package/src/access.ts

@@ -0,0 +1,50 @@
+/** IAM vocabulary shared by the Control runtime, its Access schema and the console. */
+
+/** Durable IAM application id of the console — a deployed identity, not configuration branding (ADR-0024). */
+export const CONTROL_APP_ID = 'vozka'
+
+/**
+ * The actions Control authorizes against. AWS-IAM-style dotted strings; IAM's `permits` matches
+ * them (incl. `*` / `prefix.*` wildcards in granted roles).
+ */
+export const CONTROL_ACTIONS = Object.freeze({
+	/** Trigger a deploy run (the manual "Deploy" button / triggerDeploy RPC). Scoped by app/environment. */
+	DEPLOY_TRIGGER: 'deploy.trigger',
+	/** Read deploy runs + their logs (run history API). Scoped by app/environment. */
+	DEPLOY_READ: 'deploy.read',
+	/** Manage the app registry (apps + app_envs CRUD, onboarding). Scoped by app (global to create). */
+	APP_MANAGE: 'app.manage',
+	/** Manage provider-owned deployment namespaces and their lifecycle. Global because namespaces may span apps. */
+	NAMESPACE_MANAGE: 'namespace.manage',
+	/**
+	 * Manage SECRET VALUES + their references. Gates the app_secrets reference CRUD (scoped by app) AND
+	 * writing/rotating/deleting the encrypted per-app/app-env VALUES in the vault. The value is
+	 * write-only over the API; it is never returned. (Platform creds — the CF token, IAM
+	 * provisioning creds — are fabrika's own Worker secrets, not managed through this action.)
+	 */
+	SECRET_MANAGE: 'secret.manage',
+	/** Manage the platform GitHub source connection. Global because it changes control-wide credentials. */
+	SOURCE_CONNECTION_MANAGE: 'source.connection.manage',
+	/** Read the files of one's own Git workspaces on an authoring target (ADR-0049). Scoped by app/environment. */
+	SOURCE_WORKSPACE_READ: 'source.workspace.read',
+	/** Create Git workspaces and commit to them on an authoring target. Scoped by app/environment. */
+	SOURCE_WORKSPACE_WRITE: 'source.workspace.write',
+	/** Open a pull request from one's own workspace to the default branch. Scoped by app/environment. */
+	SOURCE_PULL_REQUEST_CREATE: 'source.pull-request.create',
+	/**
+	 * Approve a widening of an environment's access and change its `protected` flag (ADR-0050). Outside `deploy.*`, so
+	 * the operator role does not hold it; only a human user principal in the console may use it. Scoped by app/environment.
+	 */
+	ACCESS_APPROVE: 'access.approve',
+})
+
+/**
+ * The scope dimensions Control authorizes within (flat + independent IAM semantics):
+ *  - `app`         — scoped to one registered app (its `id`), across every environment.
+ *  - `environment` — scoped to one environment name (e.g. only `stage`), across apps.
+ * A grant with neither scope is global.
+ */
+export const CONTROL_SCOPES = Object.freeze({
+	APP: 'app',
+	ENVIRONMENT: 'environment',
+})

package/src/index.ts

@@ -1,6 +1,7 @@
 import type { JsonValue, ProviderEnvelope } from '@fabrika/provider-contract'
 import { z } from 'zod'
 
+export * from './access.js'
 export * from './builder-bootstrap.js'
 export * from './builder-connections.js'
 export * from './builder-pairing.js'
@@ -26,6 +27,25 @@ export interface InstallationDto {
 	readonly provider: string
 }
 
+/**
+ * The console actions the caller's verified token holds, in the shape of an application's caller document. The
+ * console shows and hides by it; it decides nothing, because every procedure checks its own action.
+ */
+export interface ConsoleAccessDto {
+	/** Null for a credential bound to no principal. */
+	readonly principal: { readonly id: string; readonly label: string } | null
+	/** The actions held as a global grant, so in every scope value. */
+	readonly global: readonly string[]
+	/** Each scope value the caller holds an action in, with those actions; sorted by dimension, then value. */
+	readonly scopes: readonly ConsoleScopedActionsDto[]
+}
+
+export interface ConsoleScopedActionsDto {
+	readonly type: string
+	readonly value: string
+	readonly actions: readonly string[]
+}
+
 export interface GitHubSourceRepositoryDto {
 	readonly owner: string
 	readonly name: string
@@ -81,6 +101,14 @@ export interface GitHubSourceConnectionInstallationRequiredDto extends GitHubSou
 	readonly installationUrl: string
 }
 
+/**
+ * The query parameter Control's GitHub setup URL adds when it sends the browser to the console's source page. It reports
+ * what that one return from GitHub found; the page still reads the connection state from the API.
+ */
+export const GITHUB_SETUP_OUTCOME_PARAM = 'github-setup'
+
+export type GitHubSetupOutcome = 'connected' | 'approval-requested' | 'unverified'
+
 export interface GitHubSourceConnectionConnectedDto extends GitHubSourceConnectionBaseDto {
 	readonly state: 'connected'
 	readonly connectionId: string

package/src/rpc.ts

@@ -19,6 +19,7 @@ import type {
 	AppSecretDto,
 	AppVarDto,
 	CompleteApprovalRequest,
+	ConsoleAccessDto,
 	CreateDeploymentNamespaceRequest,
 	CursorList,
 	DeploymentNamespaceDetailDto,
@@ -135,6 +136,7 @@ export interface GitHubSourceConnectionRpcContract {
 /** Portable Delivery control API shared by browser and machine callers. */
 export interface ControlRpcContract {
 	installation: RpcProcedure<void, InstallationDto>
+	consoleAccess: RpcProcedure<void, ConsoleAccessDto>
 	builderPairing: {
 		inspect: RpcProcedure<BuilderPairingProofRequest, InspectDeviceAuthorizationResult>
 		approve: RpcProcedure<BuilderPairingProofRequest, ApproveDeviceAuthorizationResult>