Files
archie/internal/infrastructure/staterpc/task_grants.go
T
sam 3f0071e27b feat(statestore): step_executions, StartStep/FinishStep under the run credential
Plan item 3 of docs/prds/execution-tree-state-machine.md (archie-core-1220), on
top of the transition tables and ErrIllegalTransition enforcement (1214/1215,
archie-core-qdbo.5):

- Migration 0017 adds step_executions -- id, org_id, workspace_id, execution_id,
  attempt, parent_id, depth, kind, name, called_execution_id, status, detail,
  tokens_used, started_at, finished_at, indexed on (execution_id, attempt, id).
  Ownership fields are stamped from the execution's row; depth is derived from
  the parent, never supplied by a caller. Existing rows gain no backfilled
  steps.
- task.Store (the workflow engine's mid-run facade) gains StartStep/FinishStep
  (5 methods, within the 8 cap), with storecontract.StepRecorder fronting them
  on the server; deadlineStore wraps both with its per-call timeout.
- The store enforces each write as one transaction: the guarded row write
  under the shared step transition table plus the transition's own
  stage_start/stage_finish event row. Staleness is decided before legality,
  the way guardTransition decides it, and the store returns the persisted
  event for the caller's post-commit publish -- the EmitDurable convention
  (the daemon's event sink skips already-persisted rows by assigned ID), which
  is why workflow.Run stops emitting stage events beside the store and no
  longer discards step-write errors: a failed start or finish parks the
  execution, and the stage does not run unrecorded. An interrupted stage
  records interrupted rather than failed; a recording failure on that
  shutdown path is logged and left to RecoverStale, which owns the
  interrupted-execution sweep in plan item 6.
- The run credential of docs/prds/orgs-and-access.md authorises StartStep and
  FinishStep on its own execution only: both requests carry the execution ID
  the grant check verifies (FinishStep carries it because the interceptor
  never reads the database), and FinishStep verifies handler-side that the
  step really is that execution's. authorizesTaskScopedCall's sanctioned
  widenings are now held as a lookup table so the next one stops growing a
  switch.
- The PRD's wire contract is StartStep(execution, attempt, parent, kind, name)
  -> step id; the responses also carry the persisted event (needed for the
  post-commit publish) and FinishStep's request carries execution_id (needed
  for the grant check) -- both noted here as deliberate additions to the PRD's
  shorthand. called_execution_id exists in the table but not yet on the wire:
  its named consumer is the workflow-call recording of plan item 4 (#1216).

Conformance drives both adapters; grant tests pin the own-execution scoping;
the wire sentinel set gains ErrInvalidStep (InvalidArgument, "step execution
invalid") for a step kind no consumer names.
2026-09-27 05:42:32 +10:00

273 lines
9.1 KiB
Go

package staterpc
import (
"context"
"crypto/rand"
"crypto/sha256"
"crypto/subtle"
"encoding/hex"
"sync"
"time"
"google.golang.org/grpc"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/metadata"
"google.golang.org/grpc/status"
pb "github.com/samcharles93/archie-core/internal/contracts/state/v1"
"github.com/samcharles93/archie-core/internal/domain/workflow/task"
)
// TaskGrants lives in the State Store process. Restart invalidates all worker
// grants; administrative credentials are never sent to workers.
type TaskGrants struct {
mu sync.Mutex
active map[int64]taskGrant
}
type taskGrant struct {
digest [32]byte
expires time.Time
}
func (g *TaskGrants) register(taskID int64, token string, lifetime time.Duration) error {
if taskID <= 0 || len(token) != 64 || lifetime <= 0 || lifetime > 7*24*time.Hour {
return status.Error(codes.InvalidArgument, "invalid task grant")
}
if _, err := hex.DecodeString(token); err != nil {
return status.Error(codes.InvalidArgument, "invalid task grant")
}
g.mu.Lock()
defer g.mu.Unlock()
if g.active == nil {
g.active = make(map[int64]taskGrant)
}
now := time.Now()
for id, grant := range g.active {
if !now.Before(grant.expires) {
delete(g.active, id)
}
}
g.active[taskID] = taskGrant{digest: sha256.Sum256([]byte(token)), expires: now.Add(lifetime)}
return nil
}
func (g *TaskGrants) revoke(token string) {
digest := sha256.Sum256([]byte(token))
g.mu.Lock()
defer g.mu.Unlock()
for id, grant := range g.active {
if grant.digest == digest {
delete(g.active, id)
}
}
}
// requestToken extracts the bearer token from ctx's metadata, if any.
func requestToken(ctx context.Context) string {
md, _ := metadata.FromIncomingContext(ctx)
if tokens := md.Get(tokenMetadataKey); len(tokens) > 0 {
return tokens[0]
}
return ""
}
// taskFor resolves token to the task ID it was issued for, or 0 if the token
// is unknown, expired, or empty.
func (g *TaskGrants) taskFor(token string) int64 {
if token == "" {
return 0
}
digest := sha256.Sum256([]byte(token))
g.mu.Lock()
defer g.mu.Unlock()
now := time.Now()
for id, grant := range g.active {
if grant.digest == digest && now.Before(grant.expires) {
return id
}
}
return 0
}
// authorizesTaskScopedCall reports whether req -- a call to one of the RPCs
// a task grant may ever authorize -- targets taskID. Every other RPC
// (including RegisterTaskGrant/RevokeTaskGrant themselves) falls through to
// false: a task grant can only ever narrow, never expand.
//
// The two workflow.call RPCs and the two step-execution writes are the
// sanctioned widenings: a workflow.call step must start its callee and read it
// back, the callee being the caller's child (docs/prds/workflow-calls.md), and
// the container records its stages and its own agent calls under the run
// credential of docs/prds/execution-tree-state-machine.md. The step requests
// carry the caller's own task ID, which the grant check verifies; the step's
// membership in that execution is a handler-side row check, so this
// interceptor never reads the database.
func authorizesTaskScopedCall(fullMethod string, req any, taskID int64) bool {
target := taskScopedTargets[fullMethod]
return target != nil && target(req) == taskID
}
// taskScopedTargets maps each RPC a task grant may ever authorize to the
// function naming the task ID its request targets (0 for a request it cannot
// read). Held as data so the sanctioned widenings stop growing a switch: a
// new authorized RPC registers one row here, and the deny-by-default rule
// above covers everything else.
var taskScopedTargets = map[string]func(any) int64{
pb.StateStoreService_Update_FullMethodName: func(req any) int64 {
r, ok := req.(*pb.UpdateRequest)
if !ok || r.Task == nil {
return 0
}
return r.Task.Id
},
pb.StateStoreService_Transition_FullMethodName: func(req any) int64 {
r, ok := req.(*pb.TransitionRequest)
if !ok {
return 0
}
return r.TaskId
},
pb.StateStoreService_InsertEvent_FullMethodName: func(req any) int64 {
r, ok := req.(*pb.InsertEventRequest)
if !ok || r.Event == nil {
return 0
}
return r.Event.TaskId
},
pb.StateStoreService_StartStep_FullMethodName: func(req any) int64 {
r, ok := req.(*pb.StartStepRequest)
if !ok {
return 0
}
return r.ExecutionId
},
pb.StateStoreService_FinishStep_FullMethodName: func(req any) int64 {
r, ok := req.(*pb.FinishStepRequest)
if !ok {
return 0
}
return r.ExecutionId
},
pb.StateStoreService_EnqueueCallTask_FullMethodName: func(req any) int64 {
r, ok := req.(*pb.EnqueueCallTaskRequest)
if !ok {
return 0
}
return r.CallerTaskId
},
pb.StateStoreService_WorkflowCallStatus_FullMethodName: func(req any) int64 {
r, ok := req.(*pb.WorkflowCallStatusRequest)
if !ok {
return 0
}
return r.CallerTaskId
},
}
// UnaryInterceptor separates administrator access from task-scoped worker
// access. A tokenless listener is permitted only on loopback by composition.
// Supplied worker tokens are still validated on loopback.
func (g *TaskGrants) UnaryInterceptor(adminToken string) grpc.UnaryServerInterceptor {
return func(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
token := requestToken(ctx)
if (adminToken == "" && token == "") || (adminToken != "" && subtle.ConstantTimeCompare([]byte(token), []byte(adminToken)) == 1) {
return handler(ctx, req)
}
if token == "" {
return nil, status.Error(codes.Unauthenticated, "missing state store token")
}
taskID := g.taskFor(token)
if taskID == 0 {
return nil, status.Error(codes.Unauthenticated, "invalid state store token")
}
if !authorizesTaskScopedCall(info.FullMethod, req, taskID) {
return nil, status.Error(codes.PermissionDenied, "task grant does not authorize this operation")
}
return handler(ctx, req)
}
}
// StreamInterceptor admits only administrators to store read streams.
func (g *TaskGrants) StreamInterceptor(adminToken string) grpc.StreamServerInterceptor {
return func(srv any, stream grpc.ServerStream, _ *grpc.StreamServerInfo, handler grpc.StreamHandler) error {
md, _ := metadata.FromIncomingContext(stream.Context())
tokens := md.Get(tokenMetadataKey)
if adminToken == "" && len(tokens) == 0 {
return handler(srv, stream)
}
if len(tokens) > 0 && adminToken != "" && subtle.ConstantTimeCompare([]byte(tokens[0]), []byte(adminToken)) == 1 {
return handler(srv, stream)
}
return status.Error(codes.PermissionDenied, "task grant does not authorize streaming reads")
}
}
func (s *server) RegisterTaskGrant(_ context.Context, r *pb.RegisterTaskGrantRequest) (*pb.RegisterTaskGrantResponse, error) {
if s.deps.Grants == nil {
return nil, status.Error(codes.Unavailable, "task grants unavailable")
}
if r.LifetimeSeconds <= 0 || r.LifetimeSeconds > 7*24*60*60 {
return nil, status.Error(codes.InvalidArgument, "invalid task grant lifetime")
}
if err := s.deps.Grants.register(r.TaskId, r.Token, time.Duration(r.LifetimeSeconds)*time.Second); err != nil {
return nil, err
}
return &pb.RegisterTaskGrantResponse{}, nil
}
func (s *server) RevokeTaskGrant(_ context.Context, r *pb.RevokeTaskGrantRequest) (*pb.RevokeTaskGrantResponse, error) {
if s.deps.Grants == nil {
return nil, status.Error(codes.Unavailable, "task grants unavailable")
}
s.deps.Grants.revoke(r.Token)
return &pb.RevokeTaskGrantResponse{}, nil
}
// RegisterTaskGrant creates fresh random material at the daemon and registers
// it at the remote authority before starting the container.
func (c *Client) RegisterTaskGrant(ctx context.Context, taskID int64, lifetime time.Duration) (string, error) {
var bytes [32]byte
if _, err := rand.Read(bytes[:]); err != nil {
return "", err
}
token := hex.EncodeToString(bytes[:])
_, err := c.client.RegisterTaskGrant(ctx, &pb.RegisterTaskGrantRequest{TaskId: taskID, Token: token, LifetimeSeconds: int64(lifetime / time.Second)})
if err != nil {
return "", unmapError(err)
}
return token, nil
}
func (c *Client) RevokeTaskGrant(ctx context.Context, token string) error {
_, err := c.client.RevokeTaskGrant(ctx, &pb.RevokeTaskGrantRequest{Token: token})
return unmapError(err)
}
// defaultGrantLifetime bounds how long an unrevoked grant stays valid if the
// daemon crashes before its deferred revoke runs. It is generous relative to
// any realistic task run, not a task timeout -- the server's own register
// additionally caps any requested lifetime at 7 days.
const defaultGrantLifetime = 24 * time.Hour
// GrantIssuer implements daemon.StateStoreGrantIssuer over a *Client,
// registering a fresh per-task credential at the remote State Store before a
// container starts and revoking it when the daemon releases the container.
type GrantIssuer struct {
Client *Client
}
func (g *GrantIssuer) Issue(task *task.Task) (string, func(), error) {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
token, err := g.Client.RegisterTaskGrant(ctx, task.ID, defaultGrantLifetime)
if err != nil {
return "", nil, err
}
return token, func() {
revokeCtx, revokeCancel := context.WithTimeout(context.Background(), 10*time.Second)
defer revokeCancel()
_ = g.Client.RevokeTaskGrant(revokeCtx, token)
}, nil
}