Merge branch 'main' into dependabot/github_actions/codecov/codecov-action-7.0.0

Author: nficano

bin/arcp

@@ -6,10 +6,10 @@ declare(strict_types=1);
 /*
  * arcp — CLI entry point (RFC §22 transports + Phase 7 commands).
  *
- *  arcp serve  ws://host:port    Run an empty runtime accepting connections.
- *  arcp tail   <session-id>      Subscribe to all events from a session.
- *  arcp send   <type> --payload  Send a single envelope and print the reply.
- *  arcp replay <after-id>        Replay an event log file from a message id.
+ *  arcp serve  --host H --port P            Run a runtime accepting WebSocket connections.
+ *  arcp tail   <ws-uri>                     Subscribe to a runtime and print every envelope.
+ *  arcp send   <ws-uri> <tool> --arguments '<json>'  Invoke a tool and print the reply.
+ *  arcp replay <db-path> --after <message-id>         Replay an event log database.
  *
  * Production deployments should subclass these commands with real auth
  * configuration; the defaults assume `none` (anonymous) for development.

docs/conformance.md

@@ -4,23 +4,26 @@ The PHP SDK targets ARCP v1.1.
 
 ## v1.1 coverage
 
-| Area | Status |
-| --- | --- |
-| Envelope JSON and typed message catalog | implemented |
-| Session open/accepted/rejected/close | implemented |
-| Ping/pong, ack, resume replay | implemented |
-| `session.list_jobs` / `session.jobs` | implemented |
-| Tool invocation and job lifecycle | implemented |
-| Agent `name@version` resolution | implemented |
-| Progress, streams, and `job.result_chunk` | implemented |
-| Permissions and leases | implemented |
-| `cost.budget` counters | implemented |
-| `model.use` leases | implemented |
-| Provisioned credentials | implemented |
-| `LEASE_SUBSET_VIOLATION` | implemented |
-| Artifacts | implemented |
-| Subscriptions and backfill | implemented |
-| Vendor extensions | implemented |
+Status legend: **Full** — matches the v1.1 wire shape; **Partial** — works
+but still diverges from the spec wire shape (tracked by the linked issues).
+
+| Area | Status | Notes |
+| --- | --- | --- |
+| Envelope JSON and typed message catalog | Partial | no top-level `event_seq` yet (#132, #152) |
+| Session hello/welcome/rejected/close | Partial | uses `session.open`/`session.accepted` not `session.hello`/`session.welcome`; no `session.closed` ack (#121, #122, #123, #130) |
+| Ping/pong, ack, resume | Partial | `ping`/`pong` not `session.ping`/`session.pong`; `ack` is advisory-only; resume uses `after_message_id` not `session.resume` + rotating token (#127, #128, #146, #55, #125) |
+| `session.list_jobs` / `session.jobs` | Partial | entries omit `lease`/`parent_job_id`/`last_event_seq`; credentials redacted from the inventory (#143) |
+| Tool invocation and job lifecycle | Partial | submission uses `tool.invoke` not `job.submit`; terminal states are `completed`/`failed` not `success`/`error`/`timed_out` (#134, #137) |
+| Agent `name@version` resolution | Full | deterministic resolution; ambiguous unversioned names are rejected |
+| Progress, streams, and `job.result_chunk` | Partial | progress body uses `percent` not `current`/`total`; inline/chunk mixing not yet prevented (#63, #147, #64, #153, #154) |
+| Permissions and leases | Partial | `expires_at` UTC/future validation and runtime expiry enforcement pending (#60, #156) |
+| `cost.budget` counters | Partial | negative metrics rejected and exact-zero allowed; no pre-dispatch budget check (#158) |
+| `model.use` leases | Full | pattern grammar matches the spec examples |
+| Provisioned credentials | Partial | per-job scoping and retried revocation in place; no startup revocation replay (#160) |
+| `LEASE_SUBSET_VIOLATION` | Full | model.use, cost.budget, and `expires_at` containment enforced |
+| Artifacts | Full | `ref()`/`fetch()` agree on expiry |
+| Subscriptions and backfill | Partial | uses `subscribe`/`subscribe.accepted` not `job.subscribe`/`job.subscribed`; principal authorization pending (#138, #151, #139) |
+| Vendor extensions | Full | core-type classification and `x-` rejection match the spec |
 
 ## v1.1 features
 

src/Auth/AuthRouter.php

@@ -15,6 +15,14 @@
  */
 final class AuthRouter
 {
+    /**
+     * Schemes reserved by RFC §8.2 but not yet implemented; presenting one
+     * surfaces UNIMPLEMENTED rather than a generic unknown-scheme rejection.
+     *
+     * @var list<string>
+     */
+    private const array RESERVED_SCHEMES = ['mtls', 'oauth2'];
+
     /** @var array<string, AuthScheme> */
     private array $schemes = [];
 
@@ -35,7 +43,7 @@ public function verify(Auth $auth, PeerInfo $client): AuthResult
     {
         if (!isset($this->schemes[$auth->scheme])) {
             // mTLS and OAuth2 are reserved (RFC §8.2) but unimplemented in v0.1.
-            if (\in_array($auth->scheme, ['mtls', 'oauth2'], true)) {
+            if (\in_array($auth->scheme, self::RESERVED_SCHEMES, true)) {
                 throw new UnimplementedException(
                     '§8.2',
                     \sprintf('auth scheme %s deferred to v0.2', $auth->scheme),

src/Auth/JwtAuth.php

@@ -8,6 +8,8 @@
 use Arcp\Messages\Session\PeerInfo;
 use Firebase\JWT\JWT;
 use Firebase\JWT\Key;
+use Psr\Log\LoggerInterface;
+use Psr\Log\NullLogger;
 
 /**
  * `signed_jwt` verification (RFC §8.2). The runtime supplies the trust
@@ -16,10 +18,14 @@
  */
 final readonly class JwtAuth implements AuthScheme
 {
+    private LoggerInterface $logger;
+
     public function __construct(
         private Key $key,
         private string $audience,
+        ?LoggerInterface $logger = null,
     ) {
+        $this->logger = $logger ?? new NullLogger();
     }
 
     #[\Override]
@@ -40,7 +46,12 @@ public function verify(Auth $auth, PeerInfo $client): AuthResult
         try {
             $decoded = JWT::decode($auth->token, $this->key);
         } catch (\Throwable $e) {
-            return AuthResult::reject('jwt verification failed: ' . $e->getMessage());
+            // Keep the wire reason opaque: the underlying decode error can
+            // leak key id, algorithm, or expiry details useful to an
+            // attacker probing trust material. Log it server-side instead.
+            $this->logger->info('jwt verification failed', ['error' => $e->getMessage()]);
+
+            return AuthResult::reject('jwt verification failed');
         }
         $claims = (array) $decoded;
         $aud = $claims['aud'] ?? null;

src/Auth/NoneAuth.php

@@ -29,6 +29,10 @@ public function verify(Auth $auth, PeerInfo $client): AuthResult
         if ($auth->scheme !== 'none') {
             return AuthResult::reject('scheme mismatch');
         }
-        return AuthResult::accept($client->principal ?? $this->defaultPrincipal);
+        // Always use the configured default principal; do not trust the
+        // principal supplied in the untrusted PeerInfo block (mirrors the
+        // BearerAuth contract). Trusting it would let any anonymous peer
+        // claim an arbitrary principal and bypass per-principal isolation.
+        return AuthResult::accept($this->defaultPrincipal);
     }
 }

src/Cli/ServeCommand.php

@@ -44,12 +44,33 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $this->startWebSocketServer($runtime, $host, $port);
         $output->writeln(\sprintf('<info>arcp listening on ws://%s:%d/</info>', $host, $port));
 
-        // Block; pressing Ctrl-C kills the process. Production deployments
-        // should wire SIGINT/SIGTERM via the EventLoop driver.
+        // Stop the loop on SIGINT/SIGTERM for a graceful shutdown where the
+        // driver supports signal handling; otherwise the default disposition
+        // (Ctrl-C terminates the process) applies.
+        $this->installSignalHandlers($output);
         EventLoop::run();
         return Command::SUCCESS;
     }
 
+    private function installSignalHandlers(OutputInterface $output): void
+    {
+        if (!\defined('SIGINT') || !\defined('SIGTERM')) {
+            return;
+        }
+        $stop = static function () use ($output): void {
+            $output->writeln('<info>arcp shutting down</info>');
+            EventLoop::getDriver()->stop();
+        };
+        foreach ([\SIGINT, \SIGTERM] as $signal) {
+            try {
+                EventLoop::onSignal($signal, $stop);
+            } catch (\Revolt\EventLoop\UnsupportedFeatureException) {
+                // Loop driver lacks signal support; rely on default handling.
+                return;
+            }
+        }
+    }
+
     /** @return array{0: string, 1: int} */
     private function parseListenOptions(InputInterface $input): array
     {

src/Cli/TailCommand.php

@@ -53,7 +53,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $client->open(
             Auth::none(),
             new PeerInfo('arcp-tail', Version::IMPL_VERSION),
-            new Capabilities(subscriptions: true, anonymous: true),
+            new Capabilities(subscriptions: true, anonymous: true, features: ['subscribe']),
         );
 
         $client->subscribe(

src/Client/ARCPClient.php

@@ -16,6 +16,8 @@
 use Arcp\Envelope\MessageCatalog;
 use Arcp\Envelope\MessageTypeRegistry;
 use Arcp\Errors\InvalidArgumentException;
+use Arcp\Errors\TransportClosedException;
+use Arcp\Errors\UnimplementedException;
 use Arcp\Ids\ArtifactId;
 use Arcp\Ids\IdempotencyKey;
 use Arcp\Ids\JobId;
@@ -468,19 +470,41 @@ private function runReadLoop(?Cancellation $cancellation): void
     {
         try {
             while (!$this->session->transport->isClosed()) {
-                $env = $this->session->transport->receive($cancellation);
-                if (!$env instanceof Envelope) {
+                if (!$this->readOnce($cancellation)) {
                     break;
                 }
-                if ($env->payload instanceof ResultChunk) {
-                    $this->resultChunks->push($env->payload);
-                }
-                $this->router->handle($env);
             }
         } catch (\Throwable $e) {
             $this->logger->warning('client read-loop ended', ['error' => $e->getMessage()]);
         } finally {
             $this->pending->failAll(new \RuntimeException('read loop ended'));
         }
     }
+
+    /**
+     * Process a single inbound frame. Returns false when the loop should
+     * stop (clean EOF or transport closure). A single undecodable or
+     * unknown-type frame is logged and skipped so one bad frame from the
+     * peer cannot kill the session (RFC §5 forward-compatibility).
+     */
+    private function readOnce(?Cancellation $cancellation): bool
+    {
+        try {
+            $env = $this->session->transport->receive($cancellation);
+        } catch (TransportClosedException $e) {
+            $this->logger->warning('client read-loop ended', ['error' => $e->getMessage()]);
+            return false;
+        } catch (InvalidArgumentException | UnimplementedException $e) {
+            $this->logger->warning('client dropped undecodable frame', ['error' => $e->getMessage()]);
+            return true;
+        }
+        if (!$env instanceof Envelope) {
+            return false;
+        }
+        if ($env->payload instanceof ResultChunk) {
+            $this->resultChunks->push($env->payload);
+        }
+        $this->router->handle($env);
+        return true;
+    }
 }

src/Client/ResultChunkAssembler.php

@@ -6,6 +6,7 @@
 
 use Arcp\Errors\InvalidArgumentException;
 use Arcp\Messages\Execution\ResultChunk;
+use Arcp\Messages\Execution\ResultChunkEncoding;
 
 /**
  * Collects `job.result_chunk` messages by result id and assembles final
@@ -57,13 +58,23 @@ public function assemble(string $resultId): string
         $this->assertContiguous($resultId, $chunks);
         $out = '';
         foreach ($chunks as $chunk) {
-            $out .= $chunk->encoding === 'base64'
+            $out .= $chunk->encoding === ResultChunkEncoding::Base64
                 ? $this->decodeBase64($chunk)
                 : $chunk->data;
         }
+        $this->forget($resultId);
         return $out;
     }
 
+    /**
+     * Release all buffered chunks for an assembled (or abandoned) result so a
+     * long-lived client streaming many results does not grow without bound.
+     */
+    public function forget(string $resultId): void
+    {
+        unset($this->chunks[$resultId], $this->complete[$resultId]);
+    }
+
     /** @param array<int, ResultChunk> $chunks */
     private function assertContiguous(string $resultId, array $chunks): void
     {

src/Envelope/Envelope.php

@@ -77,25 +77,28 @@ public function type(): string
      */
     public function withCorrelationId(?MessageId $correlationId): self
     {
-        return new self(
-            id: $this->id,
-            payload: $this->payload,
-            timestamp: $this->timestamp,
-            priority: $this->priority,
-            sessionId: $this->sessionId,
-            jobId: $this->jobId,
-            streamId: $this->streamId,
-            subscriptionId: $this->subscriptionId,
-            traceId: $this->traceId,
-            spanId: $this->spanId,
-            parentSpanId: $this->parentSpanId,
-            correlationId: $correlationId,
-            causationId: $this->causationId,
-            idempotencyKey: $this->idempotencyKey,
-            source: $this->source,
-            target: $this->target,
-            arcp: $this->arcp,
-            extensions: $this->extensions,
-        );
+        return $this->with(['correlationId' => $correlationId]);
+    }
+
+    /**
+     * Return a copy carrying a different payload, preserving every other
+     * field. Used for log redaction so new envelope fields are retained
+     * automatically.
+     */
+    public function withPayload(MessageType $payload): self
+    {
+        return $this->with(['payload' => $payload]);
+    }
+
+    /**
+     * Rebuild this immutable envelope with the given field overrides.
+     * Property names match the constructor parameter names, so a new field
+     * is covered automatically without touching every wither.
+     *
+     * @param array<string, mixed> $overrides
+     */
+    private function with(array $overrides): self
+    {
+        return new self(...[...get_object_vars($this), ...$overrides]);
     }
 }