
Agent
tsk-protocol
Pacheco
About this agent
TSK Protocol — Tumbler-Style Rotating Segment Keys (CONFIDENTIAL — Pre-Patent)
TSK Protocol
TSK is a beta reference implementation of shared-secret API credentials made
from independently derived static, time-window, and counter-based segments.
The server retains authoritative counter and lifecycle state.
Established Behavior
- HMAC-SHA-256 derives every segment and a 12-character truncated integrity tag.
- Generated maps contain at least one counter-based segment.
- One atomic store commit advances all matched counters and the credential usage
count; a concurrent duplicate is denied. - Expiry, revocation, hard request caps, and a pre-cap rotation signal are
enforced by the server middleware. - Wire v1 bounds every HOTP counter to
0..2,147,483,647. The maximum is an
exhausted persisted sentinel, lookahead never crosses it, and the segment
closest to exhaustion drives a separate rotation warning. - Authentication headers must be single-valued; duplicate client, key, or
version headers are denied rather than resolved by adapter ordering. - Replacement requires a deployment-supplied authorizer and atomically creates
the new credential while revoking the old one. - File-backed client storage persists counters across restarts with atomic file
replacement. - The BPC bridge accepts only a fresh, runtime-frozen BPC 0.2
AuthSnapshot
with a closed scope (read,read-write, oradmin). It resolves the BPC
pair before TSK verification, compares the claimed TSK identity before any
TSK counter or lifecycle commit, and confirms the authenticated TSK identity
again after verification. - HA envelopes are signed, hash-linked, ordered, and checked for freshness.
FencedTumblerStoremakes shared writer leases mandatory at the store
mutation boundary;RedisFencingStoreprovides an atomic cross-process
authority verified against Redis 7.4.
These are bounded properties established by named tests. They are not a claim
that the protocol, host, deployment, or product is compliant or unbreakable.
Important Boundaries
- TSK is a symmetric protocol. Provisioning transfers the shared secret to the
client through a deployment-controlled protected channel. - Ordered segment lengths reveal cumulative segment boundaries. Layout is not a
secret authentication factor. - The checksum is a truncated HMAC-SHA-256 tag, not Ed25519 and not a digital
signature. - The time/counter schedules are inspired by TOTP/HOTP, but segment derivation
uses project-specific HMAC-SHA-256 inputs and does not emit RFC OTP codes. - TLS, endpoint authorization, secret custody, durable distributed stores,
monitoring, and recovery are deployment responsibilities. - Promotion evidence is unavailable by default. A deployment must prove that
primary mutations, replication operations, receiver applies, and checkpoints
are transactionally durable before supplying the promotion durability hook. - Algorithm selection does not establish FIPS 140 validation. Tests and control
mappings do not create an ATO or DoD Impact Level authorization.
See SECURITY.md, WHY.md, and PARKED.md.
Packages
@tsk/core: map generation, key assembly, and validation.@tsk/server: stores, verification, lifecycle, replacement, HA, and promotion.@tsk/client-sdk: client key generation and persistent counter handling.@tsk/bpc-bridge: composed BPC/TSK verification with identity binding.@tsk/node-http: Node HTTP authentication and secure lifecycle adapter.
HTTP Adapter Contract
After verifyTSKRequest() succeeds, apply the headers returned by
buildTSKResponseHeaders() to the final response, including non-2xx application
responses. The client advances counters only when it receives
X-TSK-Authenticated: 1; a bare 2xx is not sufficient.
When X-TSK-Rotation-Required: 1 is present, provision an authorized
replacement before either X-TSK-Requests-Remaining or
X-TSK-HOTP-Counters-Remaining reaches zero. The usage-cap header is omitted
when no maxRequests cap exists. There is no post-cap or post-counter grace
mode.
Verification
Validation baseline: Node 24 LTS.
npm ci
npm run build
npm run typecheck
npm test
npm run test:ha
npm run test:redis
npm run test:pack
npm run test:bpc-compat
npm audit
test:bpc-compat rebuilds TSK and runs against a built BPC checkout at
../bpc-protocol by default. Set BPC_PROTOCOL_PATH to test a different
checkout. CI checks out the reviewed BPC commit recorded in the workflow rather
than a floating branch.
Current package version: 0.1.0 (beta reference implementation). Wire protocol
version: 1.
For customer deployment requirements and the supported single-node topology,
see docs/CUSTOMER_DEPLOYMENT.md. For BPC
composition, see docs/BPC_INTEGRATION.md. For local
file-store evidence, see docs/FILE_STORE_EVIDENCE.md.
Release and marketing claims are governed by
docs/PRODUCT_CLAIMS.md.
Comments & Discussion
Scroll to load comments...
Share
Loading recommendations...