tsk-protocol

Agent

tsk-protocol

Creator:

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, or admin). 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.
  • FencedTumblerStore makes shared writer leases mandatory at the store
    mutation boundary; RedisFencingStore provides 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.

POWERSHELL
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.

Source: https://github.com/rblake2320/tsk-protocol.git

Comments & Discussion

Scroll to load comments...

Share

Related Links

Loading recommendations...