feat: per-ref policies on REST endpoints across all SDKs by unknwon · Pull Request #30 · pierrecomputer/sdk

unknwon · 2026-05-22T21:04:13Z

Summary

Extends the optional ops/refs JWT policy claims to every ref-mutating REST method in all three SDKs (Go, TypeScript, Python). Previously only remote-URL token minting accepted ref policies — REST methods like createBranch, merge, createCommit, notes, etc. silently dropped them despite the gateway enforcing the same claim on those endpoints.
Adds OP_NO_PUSH / OpNoPush constant alongside the existing OP_NO_FORCE_PUSH.
Fixes a pre-existing inconsistency in RepoImpl.create_branch (Python) where policy-denied responses were swallowed into a generic \"HTTP 409\" message; it now falls back to the error key like create_tag/delete_tag/delete_branch already did.
Bumps minor versions: Go 0.8.0 → 0.9.0, TS 1.8.0 → 1.9.0, Python 1.9.0 → 1.10.0.

Refs:

End-to-end validation against acme staging

Verified by minting tokens via each SDK and exercising the gateway directly:

Test	Go	TypeScript	Python
JWT `refs` claim correctly encoded	✓	✓	✓
`create_branch feature/blocked` denied by `refs/heads/feature/*=no-push`	✓	✓	✓
`create_tag v-blocked` denied by `refs/tags/*=no-push`	✓	✓	✓
`create_branch topic/allowed` (non-matching deny) succeeds	✓	✓	✓
`create_branch release/v1` first-match-wins (explicit allow before `*=no-push`)	✓	✓	✓

Test plan

Go: go build ./... && go test ./...
TypeScript: pnpm run build && pnpm vitest run (178 tests passing)
Python: pytest tests/ (159 tests passing)
End-to-end staging tests against acme tenant — all SDKs PASS

Extend the optional `ops`/`refs` JWT policy claims to every ref-mutating operation in the Go, TypeScript, and Python SDKs. Previously only the remote-URL token minting accepted ref policies; REST methods like create_branch, merge, commit, and notes silently dropped them. Adds `OP_NO_PUSH` / `OpNoPush` constant alongside the existing `OP_NO_FORCE_PUSH`, fixes a pre-existing inconsistency in the Python SDK where create_branch error responses didn't fall back to the `error` key, and verifies end-to-end against the acme staging tenant. Bumps: Go 0.8.0->0.9.0, TS 1.8.0->1.9.0, Python 1.9.0->1.10.0.

Copilot

Pull request overview

This PR extends JWT policy support so per-ref policy rules (refs claim) are carried through to ref-mutating REST endpoints across the Go, TypeScript, and Python SDKs (not just remote URL minting), adds a no-push policy constant in each SDK, updates docs, and bumps SDK versions accordingly.

Changes:

Add refs (per-ref, ordered “first match wins”) policy support and propagate ops/refs through ref-mutating REST calls in Go/TS/Python SDKs.
Add no-push policy constant (OP_NO_PUSH / OpNoPush) and helpers to encode refs into the JWT claim shape.
Update skill/docs and bump package versions; add/extend unit tests plus optional live smoke scripts.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
skills/code-storage/SKILL.md	Documents repo-wide `ops` vs per-ref `refs`, adds `no-push`, and examples across SDKs.
packages/code-storage-typescript/tests/ref-policies-live.mjs	Adds a local-stack live smoke test script for ref policy enforcement.
packages/code-storage-typescript/tests/index.test.ts	Adds unit coverage asserting `refs` is encoded into JWTs and omitted when absent.
packages/code-storage-typescript/src/types.ts	Introduces `OP_NO_PUSH`, `PolicyOptions`, and per-ref policy types; threads options into ref-mutating APIs.
packages/code-storage-typescript/src/jwt_claims.ts	Adds helper to encode `RefPolicies` into the JWT `refs` claim tuple format.
packages/code-storage-typescript/src/index.ts	Propagates `ops`/`refs` into JWT minting for ref-mutating REST methods; emits `refs` claim when present.
packages/code-storage-typescript/package.json	Bumps TypeScript SDK version to 1.9.0.
packages/code-storage-python/tests/test_client.py	Adds JWT generation tests for `refs` claim inclusion/omission.
packages/code-storage-python/tests/ref_policies_live.py	Adds a local-stack live smoke test script for ref policy enforcement.
packages/code-storage-python/pyproject.toml	Bumps Python SDK version to 1.10.0.
packages/code-storage-python/pierre_storage/version.py	Bumps Python SDK internal version constant.
packages/code-storage-python/pierre_storage/types.py	Adds `OP_NO_PUSH` and typed structures for per-ref policy rules.
packages/code-storage-python/pierre_storage/repo.py	Threads `ops`/`refs` into ref-mutating methods and improves create_branch error message extraction.
packages/code-storage-python/pierre_storage/client.py	Plumbs `refs` through internal JWT generation path.
packages/code-storage-python/pierre_storage/auth.py	Adds `encode_refs_claim` and includes `refs` in JWT payload when provided.
packages/code-storage-python/pierre_storage/init.py	Exposes new constants/types and `encode_refs_claim` in the public package API.
packages/code-storage-go/version.go	Bumps Go SDK version to 0.9.0.
packages/code-storage-go/types.go	Adds `OpNoPush` and ref policy types; extends option structs to carry `Ops`/`Refs`.
packages/code-storage-go/repo.go	Propagates `Ops`/`Refs` into JWT generation for ref-mutating repo methods.
packages/code-storage-go/repo_test.go	Adds unit coverage asserting `refs` claim inclusion/omission in minted JWTs.
packages/code-storage-go/jwt_claims.go	Adds helper to encode ref policies into JWT `refs` claim shape.
packages/code-storage-go/jwt_claims_test.go	Adds unit coverage for `encodeRefsClaim` encoding behavior.
packages/code-storage-go/diff_commit.go	Propagates `Ops`/`Refs` into diff-commit JWT generation.
packages/code-storage-go/commit.go	Propagates `Ops`/`Refs` into commit builder JWT generation.
packages/code-storage-go/client.go	Emits `refs` claim when present during JWT generation.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Per-op REST options never had an `ops` field on main; my earlier commit added one alongside `refs`. Remove it — `ops` belongs on the URL minting path (RemoteURLOptions only), and per-op REST calls take `refs` only.

The live test's `import ... from '../src/jwt_claims.ts'` failed under plain node (no TS loader). Take encodeRefsClaim from the dist barrel that loadGitStorage already imports, so the script runs with `node`.

Reorder the policy documentation so the per-ref `refs` claim is presented as the way to add branch protection. The repo-wide `ops` claim is now labeled "legacy — do not use in new code" and explicitly redirects to the equivalent `refs: [{ pattern: '*', ops: [...] }]` form. The example procedure (Mint a Force-Push-Prevented Remote URL) and the JWT payload example are updated to use `refs` so anyone copying from the skill writes the modern form.

… present

Copilot

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated 3 comments.

The single-word `refs` SDK option name was confusing next to the JWT `refs` claim and the various `ref`/`refs/heads/...` strings in this code. Rename the SDK-surface field so it reads as "ref policies": - TypeScript: `PolicyOptions.refs` → `refPolicies` (on `GetRemoteURLOptions` and every option interface that extended `PolicyOptions`). Type alias `RefPolicies` kept. - Go: every struct field `Refs RefPolicies` → `RefPolicies RefPolicyList`. Type renamed from `RefPolicies` to `RefPolicyList` to avoid colliding with the new field name. - Python: every kwarg `refs: Optional[Refs]` → `ref_policies`. Type alias `Refs` kept. `_build_jwt_options` helper param renamed to match. The wire JWT claim remains `"refs"` on all three SDKs (verified in `encodeRefsClaim` / `encode_refs_claim` and the JWT-mint paths). No gateway-side change is needed. Also tidies em-dashes and clause-joining semicolons in deprecation comments and docstrings touched on this branch, and updates the code examples in `skills/code-storage/SKILL.md` to the new field name.

…ff JWT options

unknwon · 2026-05-26T18:09:18Z

Merging as-is, happy to address post-merge feedback!

unknwon requested a review from Copilot May 22, 2026 21:06

Copilot started reviewing on behalf of unknwon May 22, 2026 21:07 View session

Copilot AI reviewed May 22, 2026

View reviewed changes

Comment thread packages/code-storage-go/jwt_claims.go

Comment thread packages/code-storage-go/jwt_claims_test.go

Comment thread packages/code-storage-typescript/tests/ref-policies-live.mjs Outdated

unknwon added 4 commits May 22, 2026 17:18

drop per-op ops field; ref policies on REST calls take refs only

df4e54c

Per-op REST options never had an `ops` field on main; my earlier commit added one alongside `refs`. Remove it — `ops` belongs on the URL minting path (RemoteURLOptions only), and per-op REST calls take `refs` only.

ref-policies-live.mjs: import encodeRefsClaim from dist, not src .ts

d19009d

The live test's `import ... from '../src/jwt_claims.ts'` failed under plain node (no TS loader). Take encodeRefsClaim from the dist barrel that loadGitStorage already imports, so the script runs with `node`.

skills: clarify legacy ops folding — merges into existing * rule when…

9579d55

… present

unknwon requested a review from Copilot May 26, 2026 15:21

Copilot started reviewing on behalf of unknwon May 26, 2026 15:21 View session

Copilot AI reviewed May 26, 2026

View reviewed changes

Comment thread packages/code-storage-typescript/src/index.ts

Comment thread packages/code-storage-typescript/src/index.ts

Comment thread packages/code-storage-python/pierre_storage/repo.py Outdated

unknwon added 3 commits May 26, 2026 11:37

ts: fix indentation of refPolicies in createCommit/createCommitFromDi…

72f659f

…ff JWT options

1231

afda2c5

unknwon requested review from fat and jcrosby May 26, 2026 17:27

python linter fix

982d433

jcrosby approved these changes May 26, 2026

View reviewed changes

unknwon merged commit 395c66a into main May 26, 2026
3 checks passed

unknwon deleted the jc/ref-policies branch May 26, 2026 18:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: per-ref policies on REST endpoints across all SDKs#30

feat: per-ref policies on REST endpoints across all SDKs#30
unknwon merged 9 commits into
mainfrom
jc/ref-policies

unknwon commented May 22, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

unknwon commented May 26, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

unknwon commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

End-to-end validation against acme staging

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

unknwon commented May 26, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

unknwon commented May 22, 2026 •

edited

Loading