# `nupp.runtime.services.tls` Provider protocol for `host.tls` API 1. Setup selects this service before requiring `nupp.io.tls`. The facade retains the provider and supplies its explicit receiver. The provider wraps an opaque network stream handle, so its transport representation must agree with the selected `nupp.runtime.services.net` implementation. Wrapping creates TLS state; handshake and I/O then report pending work to the facade, which drives readiness. Verification is a policy input and an observable session result. Do not report a verified peer merely because a handshake completed with verification disabled. ALPN protocol text describes the negotiated result; resumed is an optional observation. closeNotify sends the TLS shutdown notification and may need further progress. destroy releases session state; the owning public connection separately controls the underlying network stream. No method may resolve or switch providers. ## Types ### `Provider` _interface_ ```nupp interface Provider readonly wrap: function( self: Provider, handle: any, server: boolean, hostname: string, certificate: string, privateKey: string, authority: string?, protocols: string, verify: boolean ): (any?, string?) readonly handshake: function(self: Provider, session: any): (boolean?, string?) readonly verified: function(self: Provider, session: any): boolean readonly resumed: (function(self: Provider, session: any): boolean)? readonly read: function(self: Provider, session: any, wanted: integer): (string?, string?) readonly write: function(self: Provider, session: any, bytes: string): (integer?, string?) readonly flushed: function(self: Provider, session: any): (boolean, string?) readonly closeNotify: function(self: Provider, session: any): (boolean, string?) readonly destroy: function(self: Provider, session: any): nil readonly connected: function(self: Provider, session: any): boolean readonly protocol: function(self: Provider, session: any): string? end ``` #### Methods ##### `wrap` ```nupp wrap: function( self: Provider, handle: any, server: boolean, hostname: string, certificate: string, privateKey: string, authority: string?, protocols: string, verify: boolean ): (any?, string?) ``` Creates session state over a compatible network handle. Certificate, private key, authority, hostname, and ALPN options follow the public TLS API. Returns the session or nil and an error. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `handle` | `any` | | | `server` | `boolean` | | | `hostname` | `string` | | | `certificate` | `string` | | | `privateKey` | `string` | | | `authority` | `string?` | | | `protocols` | `string` | | | `verify` | `boolean` | | ###### Returns | Type | Description | | --- | --- | | `any?` | | | `string?` | | ##### `handshake` ```nupp handshake: function(self: Provider, session: any): (boolean?, string?) ``` Returns true when ready, false while pending, or nil and an error. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | ###### Returns | Type | Description | | --- | --- | | `boolean?` | | | `string?` | | ##### `verified` ```nupp verified: function(self: Provider, session: any): boolean ``` Reports whether peer verification succeeded for this session. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `read` ```nupp read: function(self: Provider, session: any, wanted: integer): (string?, string?) ``` Returns bytes, nil while pending, an empty string at EOF, or nil and an error. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | | `wanted` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `string?` | | | `string?` | | ##### `write` ```nupp write: function(self: Provider, session: any, bytes: string): (integer?, string?) ``` Returns bytes accepted, nil while pending, or nil and an error. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | | `bytes` | `string` | | ###### Returns | Type | Description | | --- | --- | | `integer?` | | | `string?` | | ##### `flushed` ```nupp flushed: function(self: Provider, session: any): (boolean, string?) ``` Returns true when encrypted output has drained, false while pending, or false with an error on failure. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | ##### `closeNotify` ```nupp closeNotify: function(self: Provider, session: any): (boolean, string?) ``` Starts or continues orderly TLS shutdown; true means complete, false means pending unless accompanied by an error. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | ##### `destroy` ```nupp destroy: function(self: Provider, session: any): nil ``` Releases TLS session state; the connection owner handles the transport. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `connected` ```nupp connected: function(self: Provider, session: any): boolean ``` Reports whether the session remains connected. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `protocol` ```nupp protocol: function(self: Provider, session: any): string? ``` Returns the negotiated ALPN protocol, or nil when none is available. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Provider` | | | `session` | `any` | | ###### Returns | Type | Description | | --- | --- | | `string?` | | #### Fields ##### `resumed` ```nupp resumed: (function(self: Provider, session: any): boolean)? ``` Optionally reports whether this session resumed prior TLS state. ## Values ### `service` _variable_ ```nupp const service: services.Service ``` Canonical host.tls API 1 handle; setup selects before the public facade loads.