@ponharu/pkgflare 1.1.0 → 1.1.1

package/docs/architecture.md

@@ -34,7 +34,7 @@ Secrets provide a small deployment-owned token set with registry-wide read or pu
 
 pkgflare uses the GitHub JWT directly as the npm Bearer token. A token exchange would shorten or reshape the credential but would also require a pkgflare signing key, a new session endpoint, and another token lifecycle. Direct verification keeps standard npm/Bun requests, retains GitHub's short expiry, and makes GitHub's fixed issuer/JWKS the only signing trust root. JWKS fetches are bounded, cached, and fail closed.
 
-Normal and reusable workflows are separate trust cases. A normal rule requires the absence of `job_workflow_ref`; a reusable rule matches both the caller's `workflow_ref` and the called `job_workflow_ref`. Pull-request contexts are not accepted. Immutable numeric repository and owner IDs are authoritative; workflow path claims add execution constraints rather than replacing identity.
+Normal and reusable workflows are separate trust cases. A normal rule requires the absence of `job_workflow_ref`; a reusable rule matches both the caller's `workflow_ref` and the called `job_workflow_ref`. The called workflow may be pinned to its full commit SHA without changing the caller's branch/tag claim rules. Pull-request contexts are not accepted. Immutable numeric repository and owner IDs are authoritative; workflow path claims add execution constraints rather than replacing identity.
 
 Unexpected diagnostics identify the request and operation without recording credentials or package payloads. Normal authenticated metadata responses do contain package manifests; the privacy restriction applies to diagnostics and error responses.
 

package/docs/operations.md

@@ -109,7 +109,7 @@ githubOidc: {
 }
 ```
 
-Repository and owner IDs are decimal GitHub IDs and remain the primary repository identity checks across renames. `ref`, `workflowRef`, and optional `jobWorkflowRef` are exact matches unless they end in `*`, in which case only that final prefix wildcard is supported. Refs must be branch or tag refs. Package grants are exact scoped package names or a complete scope wildcard such as `@acme/*`; they must belong to a configured registry scope.
+Repository and owner IDs are decimal GitHub IDs and remain the primary repository identity checks across renames. `ref` and `workflowRef` accept branch or tag refs; they are exact matches unless they end in `*`, in which case only that final prefix wildcard is supported. `jobWorkflowRef` accepts the same refs or an exact 40-character lowercase hexadecimal commit SHA. Package grants are exact scoped package names or a complete scope wildcard such as `@acme/*`; they must belong to a configured registry scope.
 
 The complete normalized registry configuration must fit Cloudflare's 5 KiB per-variable limit. pkgflare checks this before deployment; prefer a scope wildcard or another registry when a very large subject/package matrix would exceed it.
 
@@ -118,6 +118,17 @@ For a normal workflow, omit `jobWorkflowRef`. A token containing `job_workflow_r
 - `repositoryId`, `repositoryOwnerId`, `ref`, and `workflowRef` identify and constrain the caller.
 - `jobWorkflowRef` identifies the called reusable workflow and its trusted ref.
 
+Pin the reusable workflow to its full commit SHA when possible:
+
+```ts
+{
+  jobWorkflowRef:
+    "acme/workflows/.github/workflows/npm-publish.yml@0123456789abcdef0123456789abcdef01234567",
+}
+```
+
+GitHub keeps the caller information in the standard claims and puts the called workflow reference in `job_workflow_ref`. A reusable workflow may be called by branch, tag, or SHA; GitHub recommends a commit SHA as the safest option for stability and security. See GitHub's documentation for [OIDC with reusable workflows](https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-with-reusable-workflows) and [calling reusable workflows](https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows#calling-a-reusable-workflow).
+
 OIDC requests from `pull_request`, `pull_request_target`, related pull-request events, and merge queues are rejected even if another claim pattern would match. Use a trusted branch, tag, or manually dispatched workflow. A `publish` grant includes reads and dist-tag changes only for its allowed packages; a `read` grant cannot publish or change tags. Metadata and tarball reads apply the same package grant.
 
 The job needs `id-token: write`. Keep a normal scope-specific `.npmrc` with `${NPM_TOKEN}`, then obtain the JWT through command substitution so it is not printed:

package/docs/specification.md

@@ -89,7 +89,7 @@ Every Registry operation requires a Bearer token. Static tokens are compared aga
 
 When GitHub OIDC is configured, a non-Secret Bearer token may be a GitHub JWT. The Worker accepts only RS256 with JWT type, the fixed `https://token.actions.githubusercontent.com` issuer and fixed GitHub JWKS URL, the configured audience, required timing and identity claims, and a maximum issued age of ten minutes. It matches numeric repository and owner IDs, branch/tag ref, caller workflow, optional reusable workflow, permission, and package. Pull-request-related and merge-group events are rejected.
 
-Normal workflow rules require `job_workflow_ref` to be absent. Reusable workflow rules require it to match `jobWorkflowRef` in addition to matching the caller's `workflow_ref`. Exact matching is the default; a terminal `*` is the only pattern syntax. OIDC package grants are enforced before metadata, tarball, publish, and dist-tag handlers.
+Normal workflow rules require `job_workflow_ref` to be absent. Reusable workflow rules require it to match `jobWorkflowRef` in addition to matching the caller's `workflow_ref`. Caller workflow refs accept exact or terminal-wildcard branch/tag refs. A reusable workflow ref additionally accepts an exact full 40-character lowercase hexadecimal commit SHA; shortened or malformed SHAs are rejected. OIDC package grants are enforced before metadata, tarball, publish, and dist-tag handlers.
 
 GitHub keys are fetched under timeout and response-size/key-count limits, cached per isolate, and refreshed after a cooldown when an unknown key is encountered. Invalid signatures/claims fail with 403. JWKS retrieval and validation failures fail closed with 503. Tokens and claims are not included in diagnostics.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ponharu/pkgflare",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Deploy a private npm registry to your own Cloudflare account.",
   "keywords": [
     "cloudflare",