@hasna/skills 0.8.1 → 0.8.3

package/README.md

@@ -324,6 +324,116 @@ are explicitly changed or a new session starts.
 
 ## Executable skills
 
+Selected local executables declaring `runtime.env` use shared execution grants
+by default. An owner or admin reviews a policy containing exact skill versions
+and bundle digests, actor IDs, station IDs, canonical workspace directories, a
+Secrets authority and vault reference names. Actual secret values stay in Secrets.
+Policy documents are private workspace data stored by the Skills service, with
+immutable revision history in SQLite or PostgreSQL; S3 is optional.
+
+For example, keep this policy input in private configuration outside the repository
+and skill bundles, replacing the example identifiers and digest with reviewed values:
+
+```json
+{
+  "grants": [{
+    "id": "provider-access",
+    "target": "local",
+    "selection": {
+      "slug": "your-skill",
+      "version": "1.0.0",
+      "bundleDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    },
+    "actors": ["user-example"],
+    "consumers": [{"stationId": "workstation", "workspaceDirectory": "/workspace/project"}],
+    "secretsAuthority": "https://vault.example.com/v1",
+    "bindings": {"PROVIDER_TOKEN": "my/provider/key"}
+  }]
+}
+```
+
+```bash
+skills grants set default --file ./policy.json --json
+skills grants show default --json --save ./policy-snapshot.json
+skills run --target local --selection-profile default \
+  --input '{"requested":"work"}' --json your-skill@1.0.0
+# Updates and revocation require the current policy revision, not the profile revision:
+skills grants set default --file ./reviewed-policy.json --if-match <policy-revision>
+skills grants show default --revision <prior-policy-revision> --json
+```
+
+Updating a policy appends a revision and atomically changes its current pointer.
+An empty `grants` array revokes shared execution access. Historical policies remain
+readable and can be submitted as a new reviewed revision for rollback; they cannot
+authorize an execution directly. Unrelated selection-profile edits do not require
+rewriting the policy. A changed executable version or digest needs a new grant.
+
+Each run resolves current authorization through the Skills API before reading
+Secrets. Missing, expired, ambiguous or revoked grants, changed selections and API
+failures stop execution without using a cached grant. Optional `expiresAt` is an
+ISO timestamp; `includeDescendants: true` permits canonical directories beneath a
+consumer's workspace root. Station and path conditions describe client context;
+they are not cryptographic machine attestation. Revocation applies to subsequent
+authorization requests, not already running processes.
+
+Grant writers need an owner/admin role and `execution-grants:write` (or
+`execution-grants:*`/`*`); `skills:*` alone cannot grant access. Policy and history
+reads need `execution-grants:read`. Execution resolution accepts `skills:read` or
+`execution-grants:resolve`. Each client still needs independent Secrets access
+to the reviewed references. Managed MCP `run_skill` and SDK `executeSelectedLocal`
+use the same fresh authorization path. `--cached` cannot consume shared grants.
+
+Explicit local binding files remain available for callers that manage their own
+authorization. These caller-supplied grants are independent of shared-policy
+revocation. Prepare a template using the configured Skills and Secrets clients:
+
+```bash
+skills run --target local --selection-profile default \
+  --secret-bindings-template --json your-skill@1.0.0 > bindings.json
+# Fill each empty entry in bindings with its reviewed vault key, never its value.
+skills run --target local --selection-profile default \
+  --secret-bindings ./bindings.json --input '{"requested":"work"}' \
+  --json your-skill@1.0.0
+```
+
+The template contains no credential values and does not execute the skill or
+read the declared secrets. Keep the reviewed file in your private configuration,
+outside the skill bundle and agent discovery directories. It uses
+`hasna.skills-secret-bindings.v1` and binds the exact Skills authority, workspace,
+profile ID and revision, canonical skill name, version and bundle digest, plus
+the current station ID (`HASNA_STATION`, otherwise the hostname), canonical
+working directory and independently configured Secrets `/v1` authority. Its
+`bindings` object maps each declared environment name to one vault key. Changing
+any bound field requires reviewing a fresh template. These are explicit local
+execution grants; selection sync does not distribute or implicitly approve them.
+
+The CLI validates the complete binding before fetching values through
+`@hasna/secrets`. It resolves current values for each run, checks returned keys
+and expiry, and injects only the declared variables into the child process.
+Missing, extra, stale or mismatched bindings refuse execution; a failing vault
+read never falls back to an ambient value or a local vault. Wrapping `skills run`
+in `secrets exec` alone does not bind a declared variable. Runtime controls such
+as `PATH`, `NODE_OPTIONS` and `SKILLS_INPUT_JSON` cannot be credential names.
+Bindings require an explicit local target and a fresh API selection; they cannot
+be used with cached, cloud or legacy remote execution. No S3 deployment is required.
+
+Run receipts retain references and scope, never resolved values or captured
+output. Returned child output redacts literal, JSON-escaped, base64 and URL-encoded
+forms of injected values. This limits accidental disclosure; local execution
+has the calling user's filesystem and network access and is not a sandbox for
+hostile code. Review the exact executable and grant only the credentials its
+effects require. Cloud admission and cloud credential delivery remain separate.
+SDK callers use `resolveSelectedRun`, `prepareSelectedSecretBindings` and
+`executeSelectedLocal(selected, { secretBindings })` through `@hasna/skills/sdk`.
+The same SDK exports `readExecutionGrantPolicy`, `saveExecutionGrantPolicy` and
+`resolveExecutionGrant`. The HTTP contract is GET/PUT
+`/v1/execution-grants/:profile`, GET
+`/v1/execution-grants/:profile/versions/:revision`, and POST
+`/v1/execution-grants/:profile/resolve`. Writes use `If-None-Match: *` to create or
+the quoted policy revision in `If-Match` to update. The API advertises
+`executionGrants: true` and grant permissions in `/v1/capabilities` when supported.
+Upgrade the API and apply its database migrations before enabling shared grants.
+
 ```bash
 skills capabilities --json
 skills run --target cloud --selection-profile default \